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