include/registry/reader.h

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