include/typelib/typedescription.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 #ifndef INCLUDED_TYPELIB_TYPEDESCRIPTION_H
  20 #define INCLUDED_TYPELIB_TYPEDESCRIPTION_H
  21
  22 #include <cppu/cppudllapi.h>
  23 #include <typelib/uik.h>
  24 #include <typelib/typeclass.h>
  25 #include <rtl/ustring.h>
  26
  27 #ifdef __cplusplus
  28 extern "C"
  29 {
  30 #endif
  31
  32 struct _typelib_TypeDescription;
  33
  34 #if defined( SAL_W32)
  35 #pragma pack(push, 8)
  36 #endif
  37
  38 /** Holds a weak reference to a type description.
  39 */
  40 typedef struct _typelib_TypeDescriptionReference
  41 {
  42     /** reference count of type; don't ever modify this by yourself, use
  43         typelib_typedescriptionreference_acquire() and typelib_typedescriptionreference_release()
  44     */
  45     sal_Int32                           nRefCount;
  46     /** number of static references of type, because of the fact that some types are needed
  47         until program termination and are commonly held static.
  48     */
  49     sal_Int32                           nStaticRefCount;
  50     /** type class of type
  51     */
  52     typelib_TypeClass                   eTypeClass;
  53     /** fully qualified name of type
  54     */
  55     rtl_uString *                       pTypeName;
  56     /** pointer to full typedescription; this value is only valid if the type is never swapped out
  57     */
  58     struct _typelib_TypeDescription *   pType;
  59     /** pointer to optimize the runtime; not for public use
  60     */
  61     void *                              pUniqueIdentifier;
  62     /** reserved for future use; 0 if not used
  63     */
  64     void *                              pReserved;
  65 } typelib_TypeDescriptionReference;
  66
  67 /** Full type description of a type. Memory layout of this struct is identical to the
  68     typelib_TypeDescriptionReference for the first six members.
  69     So a typedescription can be used as type reference.
  70 */
  71 typedef struct _typelib_TypeDescription
  72 {
  73     /** reference count; don't ever modify this by yourself, use
  74         typelib_typedescription_acquire() and typelib_typedescription_release()
  75     */
  76     sal_Int32                           nRefCount;
  77     /** number of static references of type, because of the fact that some types are needed
  78         until program termination and are commonly held static.
  79     */
  80     sal_Int32                           nStaticRefCount;
  81     /** type class of type
  82     */
  83     typelib_TypeClass                   eTypeClass;
  84     /** fully qualified name of type
  85     */
  86     rtl_uString *                       pTypeName;
  87     /** pointer to self to distinguish reference from description; for internal use only
  88     */
  89     struct _typelib_TypeDescription *   pSelf;
  90     /** pointer to optimize the runtime; not for public use
  91     */
  92     void *                              pUniqueIdentifier;
  93     /** reserved for future use; 0 if not used
  94     */
  95     void *                              pReserved;
  96
  97     /** flag to determine whether the description is complete:
  98         compound types lack of member names, enums lack of member types and names,
  99         interfaces lack of members and table init.
 100         Call typelib_typedescription_complete() if false.
 101     */
 102     sal_Bool                            bComplete;
 103     /** size of type
 104     */
 105     sal_Int32                           nSize;
 106     /** alignment of type
 107     */
 108     sal_Int32                           nAlignment;
 109     /** pointer to weak reference
 110     */
 111     typelib_TypeDescriptionReference *  pWeakRef;
 112     /** determines, if type can be unloaded (and it is possible to reloaded it)
 113     */
 114     sal_Bool                            bOnDemand;
 115 } typelib_TypeDescription;
 116
 117 /** Type description for exception types.
 118 */
 119 typedef struct _typelib_CompoundTypeDescription
 120 {
 121     /** inherits all members of typelib_TypeDescription
 122     */
 123     typelib_TypeDescription             aBase;
 124
 125     /** pointer to base type description, else 0
 126     */
 127     struct _typelib_CompoundTypeDescription * pBaseTypeDescription;
 128
 129     /** number of members
 130     */
 131     sal_Int32                           nMembers;
 132     /** byte offsets of each member including the size the base type
 133     */
 134     sal_Int32 *                         pMemberOffsets;
 135     /** members of the struct or exception
 136     */
 137     typelib_TypeDescriptionReference ** ppTypeRefs;
 138     /** member names of the struct or exception
 139     */
 140     rtl_uString **                      ppMemberNames;
 141 } typelib_CompoundTypeDescription;
 142
 143 /**
 144    Type description for struct types.
 145
 146    This is only used to represent plain struct types and instantiated
 147    polymorphic struct types; there is no representation of polymorphic struct
 148    type templates at this level.
 149
 150    @since UDK 3.2.0
 151  */
 152 typedef struct _typelib_StructTypeDescription
 153 {
 154     /**
 155        Derived from typelib_CompoundTypeDescription.
 156      */
 157     typelib_CompoundTypeDescription aBase;
 158
 159     /**
 160        Flags for direct members, specifying whether they are of parameterized
 161        type (true) or explict type (false).
 162
 163        For a plain struct type, this is a null pointer.
 164      */
 165     sal_Bool * pParameterizedTypes;
 166 } typelib_StructTypeDescription;
 167
 168 /** Type description of a sequence.
 169 */
 170 typedef struct _typelib_IndirectTypeDescription
 171 {
 172     /** inherits all members of typelib_TypeDescription
 173     */
 174     typelib_TypeDescription             aBase;
 175
 176     /** pointer to element type
 177     */
 178     typelib_TypeDescriptionReference *  pType;
 179 } typelib_IndirectTypeDescription;
 180
 181 /** Type description of an enum. The type class of this description is typelib_TypeClass_ENUM.
 182 */
 183 typedef struct _typelib_EnumTypeDescription
 184 {
 185     /** inherits all members of typelib_TypeDescription
 186     */
 187     typelib_TypeDescription             aBase;
 188
 189     /** first value of the enum
 190     */
 191     sal_Int32                           nDefaultEnumValue;
 192     /** number of enum values
 193     */
 194     sal_Int32                           nEnumValues;
 195     /** names of enum values
 196     */
 197     rtl_uString **                      ppEnumNames;
 198     /** values of enum (corresponding to names in similar order)
 199     */
 200     sal_Int32 *                         pEnumValues;
 201 } typelib_EnumTypeDescription;
 202
 203 /** Description of an interface method parameter.
 204 */
 205 typedef struct _typelib_MethodParameter
 206 {
 207     /** name of parameter
 208     */
 209     rtl_uString *                       pName;
 210     /** type of parameter
 211     */
 212     typelib_TypeDescriptionReference *  pTypeRef;
 213     /** true: the call type of this parameter is [in] or [inout]
 214         false: the call type of this parameter is [out]
 215     */
 216     sal_Bool                            bIn;
 217     /** true: the call type of this parameter is [out] or [inout]
 218         false: the call type of this parameter is [in]
 219     */
 220     sal_Bool                            bOut;
 221 } typelib_MethodParameter;
 222
 223 /** Common base type description of typelib_InterfaceMethodTypeDescription and
 224     typelib_InterfaceAttributeTypeDescription.
 225 */
 226 typedef struct _typelib_InterfaceMemberTypeDescription
 227 {
 228     /** inherits all members of typelib_TypeDescription
 229     */
 230     typelib_TypeDescription             aBase;
 231
 232     /** position of member in the interface including the number of members of
 233         any base interfaces
 234     */
 235     sal_Int32                           nPosition;
 236     /** name of member
 237     */
 238     rtl_uString *                       pMemberName;
 239 } typelib_InterfaceMemberTypeDescription;
 240
 241 /** Type description of an interface method. The type class of this description is
 242     typelib_TypeClass_INTERFACE_METHOD. The size and the alignment are 0.
 243 */
 244 typedef struct _typelib_InterfaceMethodTypeDescription
 245 {
 246     /** inherits all members of typelib_InterfaceMemberTypeDescription
 247     */
 248     typelib_InterfaceMemberTypeDescription      aBase;
 249
 250     /** type of the return value
 251     */
 252     typelib_TypeDescriptionReference *          pReturnTypeRef;
 253     /** number of parameters
 254     */
 255     sal_Int32                                   nParams;
 256     /** array of parameters
 257     */
 258     typelib_MethodParameter *                   pParams;
 259     /** number of exceptions
 260     */
 261     sal_Int32                                   nExceptions;
 262     /** array of exception types
 263     */
 264     typelib_TypeDescriptionReference **         ppExceptions;
 265     /** determines whether method is declared oneway
 266     */
 267     sal_Bool                                    bOneWay;
 268
 269     /** the interface description this method is a member of
 270     */
 271     struct _typelib_InterfaceTypeDescription *  pInterface;
 272     /** the inherited direct base method (null for a method that is not
 273         inherited)
 274
 275         @since UDK 3.2.0
 276     */
 277     typelib_TypeDescriptionReference *          pBaseRef;
 278     /** if pBaseRef is null, the member position of this method within
 279         pInterface, not counting members inherited from bases; if pBaseRef is
 280         not null, the index of the direct base within pInterface from which this
 281         method is inherited
 282
 283         @since UDK 3.2.0
 284     */
 285     sal_Int32                                   nIndex;
 286 } typelib_InterfaceMethodTypeDescription;
 287
 288 /** The description of an interface attribute. The type class of this description is
 289     typelib_TypeClass_INTERFACE_ATTRIBUTE. The size and the alignment are 0.
 290 */
 291 typedef struct _typelib_InterfaceAttributeTypeDescription
 292 {
 293     /** inherits all members of typelib_InterfaceMemberTypeDescription
 294     */
 295     typelib_InterfaceMemberTypeDescription      aBase;
 296
 297     /** determines whether attribute is read only
 298     */
 299     sal_Bool                                    bReadOnly;
 300     /** type of the attribute
 301     */
 302     typelib_TypeDescriptionReference *          pAttributeTypeRef;
 303
 304     /** the interface description this attribute is a member of
 305     */
 306     struct _typelib_InterfaceTypeDescription *  pInterface;
 307     /** the inherited direct base attribute (null for an attribute that is not
 308         inherited)
 309
 310         @since UDK 3.2.0
 311     */
 312     typelib_TypeDescriptionReference *          pBaseRef;
 313     /** if pBaseRef is null, the member position of this attribute within
 314         pInterface, not counting members inherited from bases; if pBaseRef is
 315         not null, the index of the direct base within pInterface from which this
 316         attribute is inherited
 317
 318         @since UDK 3.2.0
 319     */
 320     sal_Int32                                   nIndex;
 321     /** number of getter exceptions
 322
 323         @since UDK 3.2.0
 324     */
 325     sal_Int32                                   nGetExceptions;
 326     /** array of getter exception types
 327
 328         @since UDK 3.2.0
 329     */
 330     typelib_TypeDescriptionReference **         ppGetExceptions;
 331     /** number of setter exceptions
 332
 333         @since UDK 3.2.0
 334     */
 335     sal_Int32                                   nSetExceptions;
 336     /** array of setter exception types
 337
 338         @since UDK 3.2.0
 339     */
 340     typelib_TypeDescriptionReference **         ppSetExceptions;
 341 } typelib_InterfaceAttributeTypeDescription;
 342
 343 /** Type description of an interface.
 344
 345     <p>Not all members are always initialized (not yet initialized members being
 346     null); there are three levels:</p>
 347     <ul>
 348         <li>Minimally, only <code>aBase</code>,
 349         <code>pBaseTypeDescription</code>, <code>aUik</code>,
 350         <code>nBaseTypes</code>, and <code>ppBaseTypes</code> are initialized;
 351         <code>aBase.bComplete</code> is false.  This only happens when an
 352         interface type description is created with
 353         <code>typelib_static_mi_interface_type_init</code> or
 354         <code>typelib_static_interface_type_init</code>.</li>
 355
 356         <li>At the next level, <code>nMembers</code>, <code>ppMembers</code>,
 357         <code>nAllMembers</code>, <code>ppAllMembers</code> are also
 358         initialized; <code>aBase.bComplete</code> is still false.  This happens
 359         when an interface type description is created with
 360         <code>typelib_typedescription_newMIInterface</code> or
 361         <code>typelib_typedescription_newInterface</code>.</li>
 362
 363         <li>At the final level, <code>pMapMemberIndexToFunctionIndex</code>,
 364         <code>nMapFunctionIndexToMemberIndex</code>, and
 365         <code>pMapFunctionIndexToMemberIndex</code> are also initialized;
 366         <code>aBase.bComplete</code> is true.  This happens after a call to
 367         <code>typelib_typedescription_complete</code>.</li>
 368     </ul>
 369 */
 370 typedef struct _typelib_InterfaceTypeDescription
 371 {
 372     /** inherits all members of typelib_TypeDescription
 373     */
 374     typelib_TypeDescription                     aBase;
 375
 376     /** pointer to base type description, else 0
 377
 378         @deprecated
 379         use nBaseTypes and ppBaseTypes instead
 380     */
 381     struct _typelib_InterfaceTypeDescription *  pBaseTypeDescription;
 382     /** unique identifier of interface
 383
 384         @deprecated
 385         should always contain all-zeros
 386     */
 387     typelib_Uik                                 aUik;
 388     /** number of members
 389     */
 390     sal_Int32                                   nMembers;
 391     /** array of members; references attributes or methods
 392     */
 393     typelib_TypeDescriptionReference **         ppMembers;
 394     /** number of members including members of base interface
 395     */
 396     sal_Int32                                   nAllMembers;
 397     /** array of members including members of base interface; references attributes or methods
 398     */
 399     typelib_TypeDescriptionReference **         ppAllMembers;
 400     /** array mapping index of the member description to an index doubling for read-write
 401         attributes (called function index); size of array is nAllMembers
 402     */
 403     sal_Int32 *                                 pMapMemberIndexToFunctionIndex;
 404     /** number of members plus number of read-write attributes
 405     */
 406     sal_Int32                                   nMapFunctionIndexToMemberIndex;
 407     /** array mapping function index to member index; size of arry is nMapFunctionIndexToMemberIndex
 408     */
 409     sal_Int32 *                                 pMapFunctionIndexToMemberIndex;
 410     /** number of base types
 411
 412         @since UDK 3.2.0
 413     */
 414     sal_Int32                                   nBaseTypes;
 415     /** array of base type descriptions
 416
 417         @since UDK 3.2.0
 418     */
 419     struct _typelib_InterfaceTypeDescription ** ppBaseTypes;
 420 } typelib_InterfaceTypeDescription;
 421
 422 /** Init struct of compound members for typelib_typedescription_new().
 423 */
 424 typedef struct _typelib_CompoundMember_Init
 425 {
 426     /** type class of compound member
 427     */
 428     typelib_TypeClass   eTypeClass;
 429     /** name of type of compound member
 430
 431         For a member of an instantiated polymorphic struct type that is of
 432         parameterized type, this will be a null pointer.
 433     */
 434     rtl_uString *       pTypeName;
 435     /** name of compound member
 436     */
 437     rtl_uString *       pMemberName;
 438 } typelib_CompoundMember_Init;
 439
 440 /**
 441    Init struct of members for typelib_typedescription_newStruct().
 442
 443    @since UDK 3.2.0
 444  */
 445 typedef struct _typelib_StructMember_Init
 446 {
 447     /**
 448        Derived from typelib_CompoundMember_Init;
 449      */
 450     typelib_CompoundMember_Init aBase;
 451
 452     /**
 453        Flag specifying whether the member is of parameterized type (true) or
 454        explict type (false).
 455      */
 456     sal_Bool bParameterizedType;
 457 } typelib_StructMember_Init;
 458
 459 /** Init struct of interface methods for typelib_typedescription_new().
 460 */
 461 typedef struct _typelib_Parameter_Init
 462 {
 463     /** type class of parameter
 464     */
 465     typelib_TypeClass   eTypeClass;
 466     /** name of parameter
 467     */
 468     rtl_uString *       pTypeName;
 469     /** name of parameter
 470     */
 471     rtl_uString *       pParamName;
 472     /** true, if parameter is [in] or [inout]
 473     */
 474     sal_Bool            bIn;
 475     /** true, if parameter is [out] or [inout]
 476     */
 477     sal_Bool            bOut;
 478 } typelib_Parameter_Init;
 479
 480 #if defined( SAL_W32)
 481 #pragma pack(pop)
 482 #endif
 483
 484 /** Creates an enum type description.
 485
 486     @param ppRet inout enum type description
 487     @param pTypeName name of enum
 488     @param nDefaultValue default enum value
 489     @param nEnumValues number of enum values
 490     @param ppEnumNames names of enum values
 491     @param pEnumValues enum values
 492 */
 493 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newEnum(
 494     typelib_TypeDescription ** ppRet,
 495     rtl_uString * pTypeName,
 496     sal_Int32 nDefaultValue,
 497     sal_Int32 nEnumValues,
 498     rtl_uString ** ppEnumNames,
 499     sal_Int32 * pEnumValues )
 500     SAL_THROW_EXTERN_C();
 501
 502 /** Creates a new type description.
 503
 504     Since this function can only be used to create type descriptions for plain
 505     struct types, not for instantiated polymorphic struct types, the function
 506     typelib_typedescription_newStruct should be used instead for all struct
 507     types.
 508
 509     @param ppRet inout type description
 510     @param eTypeClass type class
 511     @param pTypeName name of type
 512     @param pType sequence: element type;
 513                  struct, Exception: base type;
 514     @param nMembers number of members if struct, exception
 515     @param pMembers array of members if struct, exception
 516 */
 517 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_new(
 518     typelib_TypeDescription ** ppRet,
 519     typelib_TypeClass eTypeClass,
 520     rtl_uString * pTypeName,
 521     typelib_TypeDescriptionReference * pType,
 522     sal_Int32 nMembers,
 523     typelib_CompoundMember_Init * pMembers )
 524     SAL_THROW_EXTERN_C();
 525
 526 /** Creates a new struct type description.
 527
 528     @param ppRet inout type description
 529     @param pTypeName name of type
 530     @param pType base type;
 531     @param nMembers number of members
 532     @param pMembers array of members
 533
 534     @since UDK 3.2.0
 535 */
 536 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newStruct(
 537     typelib_TypeDescription ** ppRet,
 538     rtl_uString * pTypeName,
 539     typelib_TypeDescriptionReference * pType,
 540     sal_Int32 nMembers,
 541     typelib_StructMember_Init * pMembers )
 542     SAL_THROW_EXTERN_C();
 543
 544 /** Creates an interface type description.
 545
 546     @param ppRet inout interface type description
 547     @param pTypeName the fully qualified name of the interface.
 548     @param nUik1 uik part; deprecated and ignored, should always be 0
 549     @param nUik2 uik part; deprecated and ignored, should always be 0
 550     @param nUik3 uik part; deprecated and ignored, should always be 0
 551     @param nUik4 uik part; deprecated and ignored, should always be 0
 552     @param nUik5 uik part; deprecated and ignored, should always be 0
 553     @param pBaseInterface base interface type, else 0
 554     @param nMembers number of members
 555     @param ppMembers members; attributes or methods
 556
 557     @deprecated
 558     use typelib_typedescription_newMIInterface instead
 559 */
 560 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newInterface(
 561     typelib_InterfaceTypeDescription ** ppRet,
 562     rtl_uString * pTypeName,
 563     sal_uInt32 nUik1, sal_uInt16 nUik2, sal_uInt16 nUik3, sal_uInt32 nUik4, sal_uInt32 nUik5,
 564     typelib_TypeDescriptionReference * pBaseInterface,
 565     sal_Int32 nMembers,
 566     typelib_TypeDescriptionReference ** ppMembers )
 567     SAL_THROW_EXTERN_C();
 568
 569 /** Creates a multiple-inheritance interface type description.
 570
 571     @param ppRet inout interface type description
 572     @param pTypeName the fully qualified name of the interface.
 573     @param nUik1 uik part; deprecated and ignored, should always be 0
 574     @param nUik2 uik part; deprecated and ignored, should always be 0
 575     @param nUik3 uik part; deprecated and ignored, should always be 0
 576     @param nUik4 uik part; deprecated and ignored, should always be 0
 577     @param nUik5 uik part; deprecated and ignored, should always be 0
 578     @param nBaseInterfaces number of base interface types
 579     @param ppBaseInterfaces base interface types
 580     @param nMembers number of members
 581     @param ppMembers members; attributes or methods
 582
 583     @since UDK 3.2.0
 584 */
 585 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newMIInterface(
 586     typelib_InterfaceTypeDescription ** ppRet,
 587     rtl_uString * pTypeName,
 588     sal_uInt32 nUik1, sal_uInt16 nUik2, sal_uInt16 nUik3, sal_uInt32 nUik4, sal_uInt32 nUik5,
 589     sal_Int32 nBaseInterfaces,
 590     typelib_TypeDescriptionReference ** ppBaseInterfaces,
 591     sal_Int32 nMembers,
 592     typelib_TypeDescriptionReference ** ppMembers )
 593     SAL_THROW_EXTERN_C();
 594
 595 /** Creates an interface method type description.
 596
 597     @param ppRet inout method type description
 598     @param nAbsolutePosition position of member including all members of base interfaces
 599     @param bOneWay determines whether method is declared oneway
 600     @param pMethodName fully qualified name of method including interface name
 601     @param eReturnTypeClass type class of return type
 602     @param pReturnTypeName type name of the return type
 603     @param nParams number of parameters
 604     @param pParams parameter types
 605     @param nExceptions number of exceptions
 606     @param ppExceptionNames type names of exceptions
 607 */
 608 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newInterfaceMethod(
 609     typelib_InterfaceMethodTypeDescription ** ppRet,
 610     sal_Int32 nAbsolutePosition,
 611     sal_Bool bOneWay,
 612     rtl_uString * pMethodName,
 613     typelib_TypeClass eReturnTypeClass,
 614     rtl_uString * pReturnTypeName,
 615     sal_Int32 nParams,
 616     typelib_Parameter_Init * pParams,
 617     sal_Int32 nExceptions,
 618     rtl_uString ** ppExceptionNames )
 619     SAL_THROW_EXTERN_C();
 620
 621 /** Creates an interface attribute type description.
 622
 623     @param ppRet inout attribute type description
 624     @param nAbsolutePosition position of this attribute including all members of base interfaces
 625     @param pAttributeName fully qualified name of attribute including interface
 626     name
 627     @param eAttributeTypeClass type class of attribute type
 628     @param pAttributeTypeName type name of attribute type
 629     @param bReadOnly determines whether attribute is read-only
 630
 631     @deprecated
 632     use typelib_typedescription_newExtendedInterfaceAttribute instead
 633 */
 634 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newInterfaceAttribute(
 635     typelib_InterfaceAttributeTypeDescription ** ppRet,
 636     sal_Int32 nAbsolutePosition,
 637     rtl_uString * pAttributeName,
 638     typelib_TypeClass eAttributeTypeClass,
 639     rtl_uString * pAttributeTypeName,
 640     sal_Bool bReadOnly )
 641     SAL_THROW_EXTERN_C();
 642
 643 /** Creates an extended interface attribute type description.
 644
 645     @param ppRet inout attribute type description
 646     @param nAbsolutePosition position of this attribute including all members of
 647     base interfaces
 648     @param pAttributeName fully qualified name of attribute including interface
 649     name
 650     @param eAttributeTypeClass type class of attribute type
 651     @param pAttributeTypeName type name of attribute type
 652     @param bReadOnly determines whether attribute is read-only
 653     @param nGetExceptions number of getter exceptions
 654     @param ppGetExceptionNames type names of getter exceptions
 655     @param nSetExceptions number of setter exceptions
 656     @param ppSetExceptionNames type names of setter exceptions
 657
 658     @since UDK 3.2.0
 659 */
 660 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newExtendedInterfaceAttribute(
 661     typelib_InterfaceAttributeTypeDescription ** ppRet,
 662     sal_Int32 nAbsolutePosition,
 663     rtl_uString * pAttributeName,
 664     typelib_TypeClass eAttributeTypeClass,
 665     rtl_uString * pAttributeTypeName,
 666     sal_Bool bReadOnly,
 667     sal_Int32 nGetExceptions, rtl_uString ** ppGetExceptionNames,
 668     sal_Int32 nSetExceptions, rtl_uString ** ppSetExceptionNames )
 669     SAL_THROW_EXTERN_C();
 670
 671 /** Increments reference count of given type description.
 672
 673     @param pDesc type description
 674 */
 675 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_acquire(
 676     typelib_TypeDescription * pDesc )
 677     SAL_THROW_EXTERN_C();
 678
 679 /** Decrements reference count of given type. If reference count reaches 0, the trype description
 680     is deleted.
 681
 682     @param pDesc type description
 683 */
 684 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_release(
 685     typelib_TypeDescription * pDesc )
 686     SAL_THROW_EXTERN_C();
 687
 688 /** Registers a type description and creates a type description reference. Type descriptions
 689     will be registered automatically if they are provided via the callback chain.
 690
 691     @param ppNewDescription inout description to be registered;
 692 */
 693 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_register(
 694     typelib_TypeDescription ** ppNewDescription )
 695     SAL_THROW_EXTERN_C();
 696
 697 /** Tests whether two types descriptions are equal, i.e. type class and names are equal.
 698
 699     @param p1 a type description
 700     @param p2 another type description
 701     @return true, if type descriptions are equal
 702 */
 703 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescription_equals(
 704     const typelib_TypeDescription * p1, const typelib_TypeDescription * p2 )
 705     SAL_THROW_EXTERN_C();
 706
 707 /** Retrieves a type description via its fully qualified name.
 708
 709     @param ppRet inout type description; *ppRet is 0, if type description was not found
 710     @param pName name demanded type description
 711 */
 712 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_getByName(
 713     typelib_TypeDescription ** ppRet, rtl_uString * pName )
 714     SAL_THROW_EXTERN_C();
 715
 716 /** Sets size of type description cache.
 717
 718     @param nNewSize new size of cache
 719 */
 720 CPPU_DLLPUBLIC void SAL_CALL typelib_setCacheSize(
 721     sal_Int32 nNewSize )
 722     SAL_THROW_EXTERN_C();
 723
 724 /** Function pointer declaration of callback function get additional descriptions. Callbacks
 725     must provide complete type descriptions (see typelib_typedescription_complete())!
 726
 727     @param pContext callback context
 728     @param ppRet inout type description
 729     @param pTypeName  name of demanded type description
 730 */
 731 typedef void (SAL_CALL * typelib_typedescription_Callback)(
 732     void * pContext, typelib_TypeDescription ** ppRet, rtl_uString * pTypeName );
 733
 734 /** Registers callback function providing additional type descriptions.
 735
 736     @param pContext callback context
 737     @param pCallback callback function
 738 */
 739 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_registerCallback(
 740     void * pContext, typelib_typedescription_Callback pCallback )
 741     SAL_THROW_EXTERN_C();
 742
 743 /** Revokes a previously registered callback function.
 744
 745     @param pContext callback context
 746     @param pCallback registered callback function
 747 */
 748 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_revokeCallback(
 749     void * pContext, typelib_typedescription_Callback pCallback )
 750     SAL_THROW_EXTERN_C();
 751
 752
 753 /*----------------------------------------------------------------------------*/
 754 /*----------------------------------------------------------------------------*/
 755 /*----------------------------------------------------------------------------*/
 756
 757 /** Creates a type description reference. This is a weak reference not holding the description.
 758     If the description is already registered, the previous one is returned.
 759
 760     @param ppTDR inout type description reference
 761     @param eTypeClass type class of type
 762     @param pTypeName name of type
 763 */
 764 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_new(
 765     typelib_TypeDescriptionReference ** ppTDR,
 766     typelib_TypeClass eTypeClass,
 767     rtl_uString * pTypeName )
 768     SAL_THROW_EXTERN_C();
 769
 770 /** Creates a type description reference. This is a weak reference not holding the description.
 771     If the description is already registered, the previous one is returned.
 772
 773     @param ppTDR inout type description reference
 774     @param eTypeClass type class of type
 775     @param pTypeName ascii name of type
 776 */
 777 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_newByAsciiName(
 778     typelib_TypeDescriptionReference ** ppTDR,
 779     typelib_TypeClass eTypeClass,
 780     const sal_Char * pTypeName )
 781     SAL_THROW_EXTERN_C();
 782
 783 /** Increments reference count of type description reference.
 784
 785     @param pRef type description reference
 786 */
 787 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_acquire(
 788     typelib_TypeDescriptionReference * pRef )
 789     SAL_THROW_EXTERN_C();
 790
 791 /** Increments reference count of type description reference. If the reference count reaches 0,
 792     then the reference is deleted.
 793
 794     @param pRef type description reference
 795 */
 796 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_release(
 797     typelib_TypeDescriptionReference * pRef )
 798     SAL_THROW_EXTERN_C();
 799
 800 /** Retrieves the type description for a given reference. If it is not possible to resolve the
 801     reference, null is returned.
 802
 803     @param[in,out] ppRet type description
 804     @param[in] pRef type description reference
 805 */
 806 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_getDescription(
 807     typelib_TypeDescription ** ppRet, typelib_TypeDescriptionReference * pRef )
 808     SAL_THROW_EXTERN_C();
 809
 810 /** Tests whether two types description references are equal, i.e. type class and names are equal.
 811
 812     @param p1 a type description reference
 813     @param p2 another type description reference
 814     @return true, if type description references are equal
 815 */
 816 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescriptionreference_equals(
 817     const typelib_TypeDescriptionReference * p1, const typelib_TypeDescriptionReference * p2 )
 818     SAL_THROW_EXTERN_C();
 819
 820 /** Assigns a type.
 821
 822     @param ppDest destination type
 823     @param pSource source type
 824 */
 825 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_assign(
 826     typelib_TypeDescriptionReference ** ppDest,
 827     typelib_TypeDescriptionReference * pSource )
 828     SAL_THROW_EXTERN_C();
 829
 830 /** Tests if values of type pAssignable can be assigned by values of type pFrom. This includes
 831     widening conversion (e.g., long assignable from short), as long as there is no data loss.
 832
 833     @param pAssignable type description of value to be assigned
 834     @param pFrom type description of value
 835 */
 836 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescription_isAssignableFrom(
 837     typelib_TypeDescription * pAssignable,
 838     typelib_TypeDescription * pFrom )
 839     SAL_THROW_EXTERN_C();
 840
 841 /** Tests if values of type pAssignable can be assigned by values of type pFrom. This includes
 842     widening conversion (e.g., long assignable from short), as long as there is no data loss.
 843
 844     @param pAssignable type of value to be assigned
 845     @param pFrom type of value
 846 */
 847 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescriptionreference_isAssignableFrom(
 848     typelib_TypeDescriptionReference * pAssignable,
 849     typelib_TypeDescriptionReference * pFrom )
 850     SAL_THROW_EXTERN_C();
 851
 852 /** Gets static type reference of standard types by type class.
 853     ADDITIONAL OPT: provides Type com.sun.star.uno.Exception for typelib_TypeClass_EXCEPTION
 854                     and com.sun.star.uno.XInterface for typelib_TypeClass_INTERFACE.
 855
 856     Thread synchronizes on typelib mutex.
 857
 858     @param eTypeClass type class of basic type
 859     @return pointer to type reference pointer
 860 */
 861 CPPU_DLLPUBLIC typelib_TypeDescriptionReference ** SAL_CALL typelib_static_type_getByTypeClass(
 862     typelib_TypeClass eTypeClass )
 863     SAL_THROW_EXTERN_C();
 864
 865 /** Inits static type reference. Thread synchronizes on typelib init mutex.
 866
 867     @param ppRef pointer to type reference pointer
 868     @param eTypeClass type class of type
 869     @param pTypeName ascii name of type
 870 */
 871 CPPU_DLLPUBLIC void SAL_CALL typelib_static_type_init(
 872     typelib_TypeDescriptionReference ** ppRef,
 873     typelib_TypeClass eTypeClass, const sal_Char * pTypeName )
 874     SAL_THROW_EXTERN_C();
 875
 876 /** Inits static sequence type reference. Thread synchronizes on typelib init mutex.
 877
 878     @param ppRef pointer to type reference pointer
 879     @param pElementType element type of sequence
 880 */
 881 CPPU_DLLPUBLIC void SAL_CALL typelib_static_sequence_type_init(
 882     typelib_TypeDescriptionReference ** ppRef,
 883     typelib_TypeDescriptionReference * pElementType )
 884     SAL_THROW_EXTERN_C ();
 885
 886 /** Inits incomplete static compound type reference. Thread synchronizes on typelib init mutex.
 887
 888     Since this function can only be used to create type descriptions for plain
 889     struct types, not for instantiated polymorphic struct types, the function
 890     typelib_static_struct_type_init should be used instead for all struct types.
 891
 892     @param ppRef pointer to type reference pointer
 893     @param eTypeClass typelib_TypeClass_STRUCT or typelib_TypeClass_EXCEPTION
 894     @param pTypeName name of type
 895     @param pBaseType base type
 896     @param nMembers number of members
 897     @param ppMembers member types
 898 */
 899 CPPU_DLLPUBLIC void SAL_CALL typelib_static_compound_type_init(
 900     typelib_TypeDescriptionReference ** ppRef,
 901     typelib_TypeClass eTypeClass, const sal_Char * pTypeName,
 902     typelib_TypeDescriptionReference * pBaseType,
 903     sal_Int32 nMembers, typelib_TypeDescriptionReference ** ppMembers )
 904     SAL_THROW_EXTERN_C();
 905
 906 /** Inits incomplete static struct type reference.
 907
 908     Thread synchronizes on typelib init mutex.
 909
 910     @param ppRef pointer to type reference pointer
 911     @param pTypeName name of type
 912     @param pBaseType base type
 913     @param nMembers number of members
 914     @param ppMembers member types
 915     @param pParameterizedTypes flags for direct members, specifying whether they
 916         are of parameterized type (true) or explict type (false); must be null
 917         for a plain struct type
 918
 919     @since UDK 3.2.0
 920 */
 921 CPPU_DLLPUBLIC void SAL_CALL typelib_static_struct_type_init(
 922     typelib_TypeDescriptionReference ** ppRef, const sal_Char * pTypeName,
 923     typelib_TypeDescriptionReference * pBaseType,
 924     sal_Int32 nMembers, typelib_TypeDescriptionReference ** ppMembers,
 925     sal_Bool const * pParameterizedTypes )
 926     SAL_THROW_EXTERN_C();
 927
 928 /** Inits incomplete static interface type reference. Thread synchronizes on typelib init mutex.
 929
 930     @param ppRef pointer to type reference pointer
 931     @param pTypeName name of interface
 932     @param pBaseType base type
 933 */
 934 CPPU_DLLPUBLIC void SAL_CALL typelib_static_interface_type_init(
 935     typelib_TypeDescriptionReference ** ppRef,
 936     const sal_Char * pTypeName,
 937     typelib_TypeDescriptionReference * pBaseType )
 938     SAL_THROW_EXTERN_C();
 939
 940 /** Inits incomplete static multiple-inheritance interface type reference.
 941     Thread synchronizes on typelib init mutex.
 942
 943     @param ppRef pointer to type reference pointer
 944     @param pTypeName name of interface
 945     @param nBaseTypes number of base types
 946     @param ppBaseTypes base types
 947
 948     @since UDK 3.2.0
 949 */
 950 CPPU_DLLPUBLIC void SAL_CALL typelib_static_mi_interface_type_init(
 951     typelib_TypeDescriptionReference ** ppRef,
 952     const sal_Char * pTypeName,
 953     sal_Int32 nBaseTypes,
 954     typelib_TypeDescriptionReference ** ppBaseTypes )
 955     SAL_THROW_EXTERN_C();
 956
 957 /** Inits incomplete static enum type reference. Thread synchronizes on typelib init mutex.
 958
 959     @param ppRef pointer to type reference pointer
 960     @param pTypeName name of enum
 961     @param nDefaultValue default enum value
 962 */
 963 CPPU_DLLPUBLIC void SAL_CALL typelib_static_enum_type_init(
 964     typelib_TypeDescriptionReference ** ppRef,
 965     const sal_Char * pTypeName,
 966     sal_Int32 nDefaultValue )
 967     SAL_THROW_EXTERN_C();
 968
 969 /** Completes a typedescription to be used for, e.g., marshalling values. COMPOUND,
 970     INTERFACE and ENUM type descriptions may be partly initialized (see typelib_static_...(),
 971     typelib_TypeDescription::bComplete). For interface type descriptions, this will also
 972     init index tables.
 973
 974     @param ppTypeDescr [inout] type description to be completed (may be exchanged!)
 975     @return true, if type description is complete
 976 */
 977 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescription_complete(
 978     typelib_TypeDescription ** ppTypeDescr )
 979     SAL_THROW_EXTERN_C();
 980
 981 /// @cond INTERNAL
 982
 983 /** Returns true, if the type description reference may lose the type description. Otherwise
 984     pType is a valid pointer and cannot be discarded through the lifetime of this reference.
 985     Remark: If the pWeakObj of the type is set too, you can avoid the call of
 986     ...getDescription(...) and use the description directly. pWeakObj == 0 means, that the
 987     description is not initialized.
 988     @internal
 989 */
 990 inline bool TYPELIB_TYPEDESCRIPTIONREFERENCE_ISREALLYWEAK( _typelib_TypeClass eTypeClass )
 991 {
 992     return (eTypeClass == typelib_TypeClass_INTERFACE_METHOD) ||
 993      (eTypeClass == typelib_TypeClass_INTERFACE_ATTRIBUTE);
 994 }
 995
 996 /** Gets a description from the reference. The description may not be locked by this call.
 997     You must use the TYPELIB_DANGER_RELEASE macro to release the description fetched with
 998     this macro.
 999     @internal
1000 */
1001 inline void TYPELIB_DANGER_GET( typelib_TypeDescription** ppMacroTypeDescr,
1002     typelib_TypeDescriptionReference* pMacroTypeRef )
1003 {
1004     if (TYPELIB_TYPEDESCRIPTIONREFERENCE_ISREALLYWEAK( pMacroTypeRef->eTypeClass ))
1005     {
1006         typelib_typedescriptionreference_getDescription( ppMacroTypeDescr, pMacroTypeRef );
1007     }
1008     else if (!pMacroTypeRef->pType || !pMacroTypeRef->pType->pWeakRef)
1009     {
1010         typelib_typedescriptionreference_getDescription( ppMacroTypeDescr, pMacroTypeRef );
1011         if (*ppMacroTypeDescr)
1012         typelib_typedescription_release( *ppMacroTypeDescr );
1013     }
1014     else
1015     {
1016         *ppMacroTypeDescr = pMacroTypeRef->pType;
1017     }
1018 }
1019
1020 /** Releases the description previouse fetched by TYPELIB_DANGER_GET.
1021     @internal
1022 */
1023 inline void TYPELIB_DANGER_RELEASE( typelib_TypeDescription* pDescription )
1024 {
1025     if (TYPELIB_TYPEDESCRIPTIONREFERENCE_ISREALLYWEAK( pDescription->eTypeClass ))
1026         typelib_typedescription_release( pDescription );
1027 }
1028
1029 /// @endcond
1030
1031 #ifdef __cplusplus
1032 }
1033 #endif
1034
1035 #endif
1036
1037 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */