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