include/registry/typereg_reader.hxx

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef INCLUDED_REGISTRY_READER_H
  21 #define INCLUDED_REGISTRY_READER_H
  22
  23 #include <registry/regdllapi.h>
  24 #include <registry/types.hxx>
  25 #include <registry/version.h>
  26
  27 #include <rtl/ustring.h>
  28 #include <sal/types.h>
  29
  30 /**
  31    Creates a type reader working on a binary blob that represents a UNOIDL type.
  32
  33    <p>If a non-null handle is returned through <code>result</code>, its
  34    reference count will be one.  Operations on a non-null handle are not
  35    multi-thread&ndash;safe.</p>
  36
  37    The type reader works directly on the given buffer, which must remain
  38    available unmodified until the type reader is destroyed
  39
  40    @param buffer the binary blob representing the type; must point to at least
  41    <code>length</code> bytes, and need only be byte-aligned
  42
  43    @param length the size in bytes of the binary blob representing the type
  44
  45    @param result an out-parameter obtaining a handle on the type reader; must
  46    not be null; if the given binary blob is malformed, or of a version larger
  47    than <code>maxVersion</code>, null is returned
  48
  49    @return false iff an out-of-memory condition occurred, in which case
  50    <code>result</code> is left unchanged, and no type reader is created
  51
  52    @since UDK 3.2.0
  53  */
  54 REG_DLLPUBLIC bool typereg_reader_create(
  55     void const * buffer, sal_uInt32 length,
  56     void ** result);
  57
  58 /**
  59    Increments the reference count of a type reader.
  60
  61    @param handle a handle on a type reader; may be null
  62
  63    @since UDK 3.2.0
  64  */
  65 REG_DLLPUBLIC void typereg_reader_acquire(void * handle);
  66
  67 /**
  68    Decrements the reference count of a type reader.
  69
  70    <p>If the reference count drops to zero, the type reader is destroyed.</p>
  71
  72    @param handle a handle on a type reader; may be null
  73
  74    @since UDK 3.2.0
  75  */
  76 REG_DLLPUBLIC void typereg_reader_release(void * handle);
  77
  78 /**
  79    Returns the binary blob version of a type reader.
  80
  81    @param handle a handle on a type reader; may be null
  82
  83    @return the version of the binary blob from which the type reader was
  84    constructed; if <code>handle</code> is null, <code>TYPEREG_VERSION_0</code>
  85    is returned
  86
  87    @since UDK 3.2.0
  88  */
  89 REG_DLLPUBLIC typereg_Version typereg_reader_getVersion(void const * handle);
  90
  91 /**
  92    Returns the documentation of a type reader.
  93
  94    @param handle a handle on a type reader; may be null
  95
  96    @param result an out-parameter obtaining the documentation string; must not
  97    be null; if <code>handle</code> is null, an empty string is returned; if an
  98    out-of-memory condition occurs, a pointer to a null pointer is returned
  99
 100    @since UDK 3.2.0
 101  */
 102 REG_DLLPUBLIC void typereg_reader_getDocumentation(
 103     void * handle, rtl_uString ** result);
 104
 105 /**
 106    Returns the file name of a type reader.
 107
 108    @param handle a handle on a type reader; may be null
 109
 110    @param result an out-parameter obtaining the file name string; must not be
 111    null; if <code>handle</code> is null, an empty string is returned; if an
 112    out-of-memory condition occurs, a pointer to a null pointer is returned
 113
 114    @since UDK 3.2.0
 115    @deprecated
 116  */
 117 REG_DLLPUBLIC void typereg_reader_getFileName(void * handle, rtl_uString ** result);
 118
 119 /**
 120    Returns the type class of a type reader.
 121
 122    <p>This function will always return the type class without the internal
 123    <code>RT_TYPE_PUBLISHED</code> flag set.  Use
 124    <code>typereg_reader_isPublished</code> to determine whether a type reader is
 125    published.</p>
 126
 127    @param handle a handle on a type reader; may be null
 128
 129    @return the type class of the type reader; if <code>handle</code> is null,
 130    <code>RT_TYPE_INVALID</code> is returned
 131
 132    @since UDK 3.2.0
 133  */
 134 REG_DLLPUBLIC RTTypeClass typereg_reader_getTypeClass(void * handle);
 135
 136 /**
 137    Returns whether a type reader is published.
 138
 139    @param handle a handle on a type reader; may be null
 140
 141    @return whether the type reader is published; if <code>handle</code> is null,
 142    <code>sal_False</code> is returned
 143
 144    @since UDK 3.2.0
 145  */
 146 REG_DLLPUBLIC bool typereg_reader_isPublished(void * handle);
 147
 148 /**
 149    Returns the type name of a type reader.
 150
 151    @param handle a handle on a type reader; may be null
 152
 153    @param result an out-parameter obtaining the type name string; must not be
 154    null; if <code>handle</code> is null, an empty string is returned; if an
 155    out-of-memory condition occurs, a pointer to a null pointer is returned
 156
 157    @since UDK 3.2.0
 158  */
 159 REG_DLLPUBLIC void typereg_reader_getTypeName(void * handle, rtl_uString ** result);
 160
 161 /**
 162    Returns the number of super types of a type reader.
 163
 164    @param handle a handle on a type reader; may be null
 165
 166    @return the number of super types of the type reader; if <code>handle</code>
 167    is null, zero is returned
 168
 169    @since UDK 3.2.0
 170  */
 171 REG_DLLPUBLIC sal_uInt16 typereg_reader_getSuperTypeCount(void * handle);
 172
 173 /**
 174    Returns the type name of a super type of a type reader.
 175
 176    @param handle a handle on a type reader; must not be null
 177
 178    @param result an out-parameter obtaining the super type's type name string;
 179    must not be null; if an out-of-memory condition occurs, a pointer to a null
 180    pointer is returned
 181
 182    @param index a valid index into the range of super types of the given type
 183    reader
 184
 185    @since UDK 3.2.0
 186  */
 187 REG_DLLPUBLIC void typereg_reader_getSuperTypeName(
 188     void * handle, rtl_uString ** result, sal_uInt16 index);
 189
 190 /**
 191    Returns the number of fields of a type reader.
 192
 193    @param handle a handle on a type reader; may be null
 194
 195    @return the number of fields of the type reader; if <code>handle</code> is
 196    null, zero is returned
 197
 198    @since UDK 3.2.0
 199  */
 200 REG_DLLPUBLIC sal_uInt16 typereg_reader_getFieldCount(void * handle);
 201
 202 /**
 203    Returns the documentation of a field of a type reader.
 204
 205    @param handle a handle on a type reader; must not be null
 206
 207    @param result an out-parameter obtaining the field's documentation string;
 208    must not be null; if an out-of-memory condition occurs, a pointer to a null
 209    pointer is returned
 210
 211    @param index a valid index into the range of fields of the given type reader
 212
 213    @since UDK 3.2.0
 214  */
 215 REG_DLLPUBLIC void typereg_reader_getFieldDocumentation(
 216     void * handle, rtl_uString ** result, sal_uInt16 index);
 217
 218 /**
 219    Returns the file name of a field of a type reader.
 220
 221    @param handle a handle on a type reader; must not be null
 222
 223    @param result an out-parameter obtaining the field's file name string; must
 224    not be null; if an out-of-memory condition occurs, a pointer to a null
 225    pointer is returned
 226
 227    @param index a valid index into the range of fields of the given type reader
 228
 229    @since UDK 3.2.0
 230    @deprecated
 231  */
 232 REG_DLLPUBLIC void typereg_reader_getFieldFileName(
 233     void * handle, rtl_uString ** result, sal_uInt16 index);
 234
 235 /**
 236    Returns the flags of a field of a type reader.
 237
 238    @param handle a handle on a type reader; must not be null
 239
 240    @param index a valid index into the range of fields of the given type reader
 241
 242    @return the flags of the given field of the type reader
 243
 244    @since UDK 3.2.0
 245  */
 246 REG_DLLPUBLIC RTFieldAccess typereg_reader_getFieldFlags(
 247     void * handle, sal_uInt16 index);
 248
 249 /**
 250    Returns the name of a field of a type reader.
 251
 252    @param handle a handle on a type reader; must not be null
 253
 254    @param result an out-parameter obtaining the field's name string; must not be
 255    null; if an out-of-memory condition occurs, a pointer to a null pointer is
 256    returned
 257
 258    @param index a valid index into the range of fields of the given type reader
 259
 260    @since UDK 3.2.0
 261  */
 262 REG_DLLPUBLIC void typereg_reader_getFieldName(
 263     void * handle, rtl_uString ** result, sal_uInt16 index);
 264
 265 /**
 266    Returns the type name of a field of a type reader.
 267
 268    @param handle a handle on a type reader; must not be null
 269
 270    @param result an out-parameter obtaining the field's type name string; must
 271    not be null; if an out-of-memory condition occurs, a pointer to a null
 272    pointer is returned
 273
 274    @param index a valid index into the range of fields of the given type reader
 275
 276    @since UDK 3.2.0
 277  */
 278 REG_DLLPUBLIC void typereg_reader_getFieldTypeName(
 279     void * handle, rtl_uString ** result, sal_uInt16 index);
 280
 281 /**
 282    Returns the value of a field of a type reader.
 283
 284    @param handle a handle on a type reader; must not be null
 285
 286    @param index a valid index into the range of fields of the given type reader
 287
 288    @param type an out-parameter obtaining the field value's type; must not be
 289    null
 290
 291    @param value an out-parameter obtaining the field value's value; must not be
 292    null
 293
 294    @return false iff an out-of-memory condition occurred, in which case
 295    <code>type</code> and <code>value</code> are left unchanged
 296
 297    @since UDK 3.2.0
 298  */
 299 REG_DLLPUBLIC bool typereg_reader_getFieldValue(
 300     void * handle, sal_uInt16 index, RTValueType * type,
 301     union RTConstValueUnion * value);
 302
 303 /**
 304    Returns the number of methods of a type reader.
 305
 306    @param handle a handle on a type reader; may be null
 307
 308    @return the number of methods of the type reader; if <code>handle</code> is
 309    null, zero is returned
 310
 311    @since UDK 3.2.0
 312  */
 313 REG_DLLPUBLIC sal_uInt16 typereg_reader_getMethodCount(void * handle);
 314
 315 /**
 316    Returns the documentation of a method of a type reader.
 317
 318    @param handle a handle on a type reader; must not be null
 319
 320    @param result an out-parameter obtaining the methods's documentation string;
 321    must not be null; if an out-of-memory condition occurs, a pointer to a null
 322    pointer is returned
 323
 324    @param index a valid index into the range of methods of the given type reader
 325
 326    @since UDK 3.2.0
 327  */
 328 REG_DLLPUBLIC void typereg_reader_getMethodDocumentation(
 329     void * handle, rtl_uString ** result, sal_uInt16 index);
 330
 331 /**
 332    Returns the flags of a method of a type reader.
 333
 334    @param handle a handle on a type reader; must not be null
 335
 336    @param index a valid index into the range of methods of the given type reader
 337
 338    @return the flags of the given method of the type reader
 339
 340    @since UDK 3.2.0
 341  */
 342 REG_DLLPUBLIC RTMethodMode typereg_reader_getMethodFlags(
 343     void * handle, sal_uInt16 index);
 344
 345 /**
 346    Returns the name of a method of a type reader.
 347
 348    @param handle a handle on a type reader; must not be null
 349
 350    @param result an out-parameter obtaining the methods's name string; must not
 351    be null; if an out-of-memory condition occurs, a pointer to a null pointer is
 352    returned
 353
 354    @param index a valid index into the range of methods of the given type reader
 355
 356    @since UDK 3.2.0
 357  */
 358 REG_DLLPUBLIC void typereg_reader_getMethodName(
 359     void * handle, rtl_uString ** result, sal_uInt16 index);
 360
 361 /**
 362    Returns the return type name of a method of a type reader.
 363
 364    @param handle a handle on a type reader; must not be null
 365
 366    @param result an out-parameter obtaining the methods's return type name
 367    string; must not be null; if an out-of-memory condition occurs, a pointer to
 368    a null pointer is returned
 369
 370    @param index a valid index into the range of methods of the given type reader
 371
 372    @since UDK 3.2.0
 373  */
 374 REG_DLLPUBLIC void typereg_reader_getMethodReturnTypeName(
 375     void * handle, rtl_uString ** result, sal_uInt16 index);
 376
 377 /**
 378    Returns the number of parameters of a method of a type reader.
 379
 380    @param handle a handle on a type reader; must not be null
 381
 382    @param index a valid index into the range of methods of the given type reader
 383
 384    @return the number of parameters of the given method of the type reader
 385
 386    @since UDK 3.2.0
 387  */
 388 REG_DLLPUBLIC sal_uInt16 typereg_reader_getMethodParameterCount(
 389     void * handle, sal_uInt16 index);
 390
 391 /**
 392    Returns the flags of a parameter of a method of a type reader.
 393
 394    @param handle a handle on a type reader; must not be null
 395
 396    @param methodIndex a valid index into the range of methods of the given type
 397    reader
 398
 399    @param parameterIndex a valid index into the range of parameters of the given
 400    method
 401
 402    @return the flags of the given parameter of the given method of the type
 403    reader
 404
 405    @since UDK 3.2.0
 406  */
 407 REG_DLLPUBLIC RTParamMode typereg_reader_getMethodParameterFlags(
 408     void * handle, sal_uInt16 methodIndex, sal_uInt16 parameterIndex);
 409
 410 /**
 411    Returns the name of a parameter of a method of a type reader.
 412
 413    @param handle a handle on a type reader; must not be null
 414
 415    @param result an out-parameter obtaining the parameter's name string; must
 416    not be null; if an out-of-memory condition occurs, a pointer to a null
 417    pointer is returned
 418
 419    @param methodIndex a valid index into the range of methods of the given type
 420    reader
 421
 422    @param parameterIndex a valid index into the range of parameters of the given
 423    method
 424
 425    @since UDK 3.2.0
 426  */
 427 REG_DLLPUBLIC void typereg_reader_getMethodParameterName(
 428     void * handle, rtl_uString ** result, sal_uInt16 methodIndex,
 429     sal_uInt16 parameterIndex);
 430
 431 /**
 432    Returns the type name of a parameter of a method of a type reader.
 433
 434    @param handle a handle on a type reader; must not be null
 435
 436    @param result an out-parameter obtaining the parameter's type name string;
 437    must not be null; if an out-of-memory condition occurs, a pointer to a null
 438    pointer is returned
 439
 440    @param methodIndex a valid index into the range of methods of the given type
 441    reader
 442
 443    @param parameterIndex a valid index into the range of parameters of the given
 444    method
 445
 446    @since UDK 3.2.0
 447  */
 448 REG_DLLPUBLIC void typereg_reader_getMethodParameterTypeName(
 449     void * handle, rtl_uString ** result, sal_uInt16 methodIndex,
 450     sal_uInt16 parameterIndex);
 451
 452 /**
 453    Returns the number of exceptions of a method of a type reader.
 454
 455    @param handle a handle on a type reader; must not be null
 456
 457    @param index a valid index into the range of methods of the given type reader
 458
 459    @return the number of exceptions of the given method of the type reader
 460
 461    @since UDK 3.2.0
 462  */
 463 REG_DLLPUBLIC sal_uInt16 typereg_reader_getMethodExceptionCount(
 464     void * handle, sal_uInt16 index);
 465
 466 /**
 467    Returns the type name of an exception of a method of a type reader.
 468
 469    @param handle a handle on a type reader; must not be null
 470
 471    @param result an out-parameter obtaining the exception's type name string;
 472    must not be null; if an out-of-memory condition occurs, a pointer to a null
 473    pointer is returned
 474
 475    @param methodIndex a valid index into the range of methods of the given type
 476    reader
 477
 478    @param exceptionIndex a valid index into the range of exceptions of the given
 479    method
 480
 481    @since UDK 3.2.0
 482  */
 483 REG_DLLPUBLIC void typereg_reader_getMethodExceptionTypeName(
 484     void * handle, rtl_uString ** result, sal_uInt16 methodIndex,
 485     sal_uInt16 exceptionIndex);
 486
 487 /**
 488    Returns the number of references of a type reader.
 489
 490    @param handle a handle on a type reader; may be null
 491
 492    @return the number of references of the type reader; if <code>handle</code>
 493    is null, zero is returned
 494
 495    @since UDK 3.2.0
 496  */
 497 REG_DLLPUBLIC sal_uInt16 typereg_reader_getReferenceCount(void * handle);
 498
 499 /**
 500    Returns the documentation of a reference of a type reader.
 501
 502    @param handle a handle on a type reader; must not be null
 503
 504    @param result an out-parameter obtaining the reference's documentation
 505    string; must not be null; if an out-of-memory condition occurs, a pointer to
 506    a null pointer is returned
 507
 508    @param index a valid index into the range of references of the given type
 509    reader
 510
 511    @since UDK 3.2.0
 512  */
 513 REG_DLLPUBLIC void typereg_reader_getReferenceDocumentation(
 514     void * handle, rtl_uString ** result, sal_uInt16 index);
 515
 516 /**
 517    Returns the flags of a reference of a type reader.
 518
 519    @param handle a handle on a type reader; must not be null
 520
 521    @param index a valid index into the range of references of the given type
 522    reader
 523
 524    @return the flags of the given reference of the type reader
 525
 526    @since UDK 3.2.0
 527  */
 528 REG_DLLPUBLIC RTFieldAccess typereg_reader_getReferenceFlags(
 529     void * handle, sal_uInt16 index);
 530
 531 /**
 532    Returns the sort of a reference of a type reader.
 533
 534    @param handle a handle on a type reader; must not be null
 535
 536    @param index a valid index into the range of references of the given type
 537    reader
 538
 539    @return the sort of the given reference of the type reader
 540
 541    @since UDK 3.2.0
 542  */
 543 REG_DLLPUBLIC RTReferenceType typereg_reader_getReferenceSort(
 544     void * handle, sal_uInt16 index);
 545
 546 /**
 547    Returns the type name of a reference of a type reader.
 548
 549    @param handle a handle on a type reader; must not be null
 550
 551    @param result an out-parameter obtaining the reference's type name string;
 552    must not be null; if an out-of-memory condition occurs, a pointer to a null
 553    pointer is returned
 554
 555    @param index a valid index into the range of references of the given type
 556    reader
 557
 558    @since UDK 3.2.0
 559  */
 560 REG_DLLPUBLIC void typereg_reader_getReferenceTypeName(
 561     void * handle, rtl_uString ** result, sal_uInt16 index);
 562
 563 #endif
 564
 565 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */