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 _TYPELIB_TYPEDESCRIPTION_H_
  20 #define _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 and union 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 union. The type class of this description is typelib_TypeClass_UNION.
 169 */
 170 typedef struct _typelib_UnionTypeDescription
 171 {
 172     /** inherits all members of typelib_TypeDescription
 173     */
 174     typelib_TypeDescription             aBase;
 175
 176     /** type of the discriminant
 177     */
 178     typelib_TypeDescriptionReference *  pDiscriminantTypeRef;
 179
 180     /** union default descriminant
 181     */
 182     sal_Int64                           nDefaultDiscriminant;
 183     /** union default member type (may be 0)
 184      */
 185     typelib_TypeDescriptionReference *  pDefaultTypeRef;
 186     /** number of union member types
 187     */
 188     sal_Int32                           nMembers;
 189     /** union member discriminant values (same order as idl declaration)
 190     */
 191     sal_Int64 *                         pDiscriminants;
 192     /** union member value types (same order as idl declaration)
 193     */
 194     typelib_TypeDescriptionReference ** ppTypeRefs;
 195     /** union member value names (same order as idl declaration)
 196     */
 197     rtl_uString **                      ppMemberNames;
 198     /** union value offset for data access
 199     */
 200     sal_Int32                           nValueOffset;
 201 } typelib_UnionTypeDescription;
 202
 203 /** Type description of an array or sequence.
 204 */
 205 typedef struct _typelib_IndirectTypeDescription
 206 {
 207     /** inherits all members of typelib_TypeDescription
 208     */
 209     typelib_TypeDescription             aBase;
 210
 211     /** array, sequence: pointer to element type
 212     */
 213     typelib_TypeDescriptionReference *  pType;
 214 } typelib_IndirectTypeDescription;
 215
 216 /** Type description of an array.
 217 */
 218 typedef struct _typelib_ArrayTypeDescription
 219 {
 220     /** inherits all members of typelib_IndirectTypeDescription
 221     */
 222     typelib_IndirectTypeDescription     aBase;
 223
 224     /** number of dimensions
 225     */
 226     sal_Int32                           nDimensions;
 227     /** number of total array elements
 228     */
 229     sal_Int32                           nTotalElements;
 230     /** array of dimensions
 231     */
 232     sal_Int32 *                         pDimensions;
 233 } typelib_ArrayTypeDescription;
 234
 235 /** Type description of an enum. The type class of this description is typelib_TypeClass_ENUM.
 236 */
 237 typedef struct _typelib_EnumTypeDescription
 238 {
 239     /** inherits all members of typelib_TypeDescription
 240     */
 241     typelib_TypeDescription             aBase;
 242
 243     /** first value of the enum
 244     */
 245     sal_Int32                           nDefaultEnumValue;
 246     /** number of enum values
 247     */
 248     sal_Int32                           nEnumValues;
 249     /** names of enum values
 250     */
 251     rtl_uString **                      ppEnumNames;
 252     /** values of enum (corresponding to names in similar order)
 253     */
 254     sal_Int32 *                         pEnumValues;
 255 } typelib_EnumTypeDescription;
 256
 257 /** Description of an interface method parameter.
 258 */
 259 typedef struct _typelib_MethodParameter
 260 {
 261     /** name of parameter
 262     */
 263     rtl_uString *                       pName;
 264     /** type of parameter
 265     */
 266     typelib_TypeDescriptionReference *  pTypeRef;
 267     /** true: the call type of this parameter is [in] or [inout]
 268         false: the call type of this parameter is [out]
 269     */
 270     sal_Bool                            bIn;
 271     /** true: the call type of this parameter is [out] or [inout]
 272         false: the call type of this parameter is [in]
 273     */
 274     sal_Bool                            bOut;
 275 } typelib_MethodParameter;
 276
 277 /** Common base type description of typelib_InterfaceMethodTypeDescription and
 278     typelib_InterfaceAttributeTypeDescription.
 279 */
 280 typedef struct _typelib_InterfaceMemberTypeDescription
 281 {
 282     /** inherits all members of typelib_TypeDescription
 283     */
 284     typelib_TypeDescription             aBase;
 285
 286     /** position of member in the interface including the number of members of
 287         any base interfaces
 288     */
 289     sal_Int32                           nPosition;
 290     /** name of member
 291     */
 292     rtl_uString *                       pMemberName;
 293 } typelib_InterfaceMemberTypeDescription;
 294
 295 /** Type description of an interface method. The type class of this description is
 296     typelib_TypeClass_INTERFACE_METHOD. The size and the alignment are 0.
 297 */
 298 typedef struct _typelib_InterfaceMethodTypeDescription
 299 {
 300     /** inherits all members of typelib_InterfaceMemberTypeDescription
 301     */
 302     typelib_InterfaceMemberTypeDescription      aBase;
 303
 304     /** type of the return value
 305     */
 306     typelib_TypeDescriptionReference *          pReturnTypeRef;
 307     /** number of parameters
 308     */
 309     sal_Int32                                   nParams;
 310     /** array of parameters
 311     */
 312     typelib_MethodParameter *                   pParams;
 313     /** number of exceptions
 314     */
 315     sal_Int32                                   nExceptions;
 316     /** array of exception types
 317     */
 318     typelib_TypeDescriptionReference **         ppExceptions;
 319     /** determines whether method is declared oneway
 320     */
 321     sal_Bool                                    bOneWay;
 322
 323     /** the interface description this method is a member of
 324     */
 325     struct _typelib_InterfaceTypeDescription *  pInterface;
 326     /** the inherited direct base method (null for a method that is not
 327         inherited)
 328
 329         @since UDK 3.2.0
 330     */
 331     typelib_TypeDescriptionReference *          pBaseRef;
 332     /** if pBaseRef is null, the member position of this method within
 333         pInterface, not counting members inherited from bases; if pBaseRef is
 334         not null, the index of the direct base within pInterface from which this
 335         method is inherited
 336
 337         @since UDK 3.2.0
 338     */
 339     sal_Int32                                   nIndex;
 340 } typelib_InterfaceMethodTypeDescription;
 341
 342 /** The description of an interface attribute. The type class of this description is
 343     typelib_TypeClass_INTERFACE_ATTRIBUTE. The size and the alignment are 0.
 344 */
 345 typedef struct _typelib_InterfaceAttributeTypeDescription
 346 {
 347     /** inherits all members of typelib_InterfaceMemberTypeDescription
 348     */
 349     typelib_InterfaceMemberTypeDescription      aBase;
 350
 351     /** determines whether attribute is read only
 352     */
 353     sal_Bool                                    bReadOnly;
 354     /** type of the attribute
 355     */
 356     typelib_TypeDescriptionReference *          pAttributeTypeRef;
 357
 358     /** the interface description this attribute is a member of
 359     */
 360     struct _typelib_InterfaceTypeDescription *  pInterface;
 361     /** the inherited direct base attribute (null for an attribute that is not
 362         inherited)
 363
 364         @since UDK 3.2.0
 365     */
 366     typelib_TypeDescriptionReference *          pBaseRef;
 367     /** if pBaseRef is null, the member position of this attribute within
 368         pInterface, not counting members inherited from bases; if pBaseRef is
 369         not null, the index of the direct base within pInterface from which this
 370         attribute is inherited
 371
 372         @since UDK 3.2.0
 373     */
 374     sal_Int32                                   nIndex;
 375     /** number of getter exceptions
 376
 377         @since UDK 3.2.0
 378     */
 379     sal_Int32                                   nGetExceptions;
 380     /** array of getter exception types
 381
 382         @since UDK 3.2.0
 383     */
 384     typelib_TypeDescriptionReference **         ppGetExceptions;
 385     /** number of setter exceptions
 386
 387         @since UDK 3.2.0
 388     */
 389     sal_Int32                                   nSetExceptions;
 390     /** array of setter exception types
 391
 392         @since UDK 3.2.0
 393     */
 394     typelib_TypeDescriptionReference **         ppSetExceptions;
 395 } typelib_InterfaceAttributeTypeDescription;
 396
 397 /** Type description of an interface.
 398
 399     <p>Not all members are always initialized (not yet initialized members being
 400     null); there are three levels:</p>
 401     <ul>
 402         <li>Minimally, only <code>aBase</code>,
 403         <code>pBaseTypeDescription</code>, <code>aUik</code>,
 404         <code>nBaseTypes</code>, and <code>ppBaseTypes</code> are initialized;
 405         <code>aBase.bComplete</code> is false.  This only happens when an
 406         interface type description is created with
 407         <code>typelib_static_mi_interface_type_init</code> or
 408         <code>typelib_static_interface_type_init</code>.</li>
 409
 410         <li>At the next level, <code>nMembers</code>, <code>ppMembers</code>,
 411         <code>nAllMembers</code>, <code>ppAllMembers</code> are also
 412         initialized; <code>aBase.bComplete</code> is still false.  This happens
 413         when an interface type description is created with
 414         <code>typelib_typedescription_newMIInterface</code> or
 415         <code>typelib_typedescription_newInterface</code>.</li>
 416
 417         <li>At the final level, <code>pMapMemberIndexToFunctionIndex</code>,
 418         <code>nMapFunctionIndexToMemberIndex</code>, and
 419         <code>pMapFunctionIndexToMemberIndex</code> are also initialized;
 420         <code>aBase.bComplete</code> is true.  This happens after a call to
 421         <code>typelib_typedescription_complete</code>.</li>
 422     </ul>
 423 */
 424 typedef struct _typelib_InterfaceTypeDescription
 425 {
 426     /** inherits all members of typelib_TypeDescription
 427     */
 428     typelib_TypeDescription                     aBase;
 429
 430     /** pointer to base type description, else 0
 431
 432         @deprecated
 433         use nBaseTypes and ppBaseTypes instead
 434     */
 435     struct _typelib_InterfaceTypeDescription *  pBaseTypeDescription;
 436     /** unique identifier of interface
 437     */
 438     typelib_Uik                                 aUik;
 439     /** number of members
 440     */
 441     sal_Int32                                   nMembers;
 442     /** array of members; references attributes or methods
 443     */
 444     typelib_TypeDescriptionReference **         ppMembers;
 445     /** number of members including members of base interface
 446     */
 447     sal_Int32                                   nAllMembers;
 448     /** array of members including members of base interface; references attributes or methods
 449     */
 450     typelib_TypeDescriptionReference **         ppAllMembers;
 451     /** array mapping index of the member description to an index doubling for read-write
 452         attributes (called function index); size of array is nAllMembers
 453     */
 454     sal_Int32 *                                 pMapMemberIndexToFunctionIndex;
 455     /** number of members plus number of read-write attributes
 456     */
 457     sal_Int32                                   nMapFunctionIndexToMemberIndex;
 458     /** array mapping function index to member index; size of arry is nMapFunctionIndexToMemberIndex
 459     */
 460     sal_Int32 *                                 pMapFunctionIndexToMemberIndex;
 461     /** number of base types
 462
 463         @since UDK 3.2.0
 464     */
 465     sal_Int32                                   nBaseTypes;
 466     /** array of base type descriptions
 467
 468         @since UDK 3.2.0
 469     */
 470     struct _typelib_InterfaceTypeDescription ** ppBaseTypes;
 471 } typelib_InterfaceTypeDescription;
 472
 473 /** Init struct of compound members for typelib_typedescription_new().
 474 */
 475 typedef struct _typelib_CompoundMember_Init
 476 {
 477     /** type class of compound member
 478     */
 479     typelib_TypeClass   eTypeClass;
 480     /** name of type of compound member
 481
 482         For a member of an instantiated polymorphic struct type that is of
 483         parameterized type, this will be a null pointer.
 484     */
 485     rtl_uString *       pTypeName;
 486     /** name of compound member
 487     */
 488     rtl_uString *       pMemberName;
 489 } typelib_CompoundMember_Init;
 490
 491 /**
 492    Init struct of members for typelib_typedescription_newStruct().
 493
 494    @since UDK 3.2.0
 495  */
 496 typedef struct _typelib_StructMember_Init
 497 {
 498     /**
 499        Derived from typelib_CompoundMember_Init;
 500      */
 501     typelib_CompoundMember_Init aBase;
 502
 503     /**
 504        Flag specifying whether the member is of parameterized type (true) or
 505        explict type (false).
 506      */
 507     sal_Bool bParameterizedType;
 508 } typelib_StructMember_Init;
 509
 510 /** Init struct of interface methods for typelib_typedescription_new().
 511 */
 512 typedef struct _typelib_Parameter_Init
 513 {
 514     /** type class of parameter
 515     */
 516     typelib_TypeClass   eTypeClass;
 517     /** name of parameter
 518     */
 519     rtl_uString *       pTypeName;
 520     /** name of parameter
 521     */
 522     rtl_uString *       pParamName;
 523     /** true, if parameter is [in] or [inout]
 524     */
 525     sal_Bool            bIn;
 526     /** true, if parameter is [out] or [inout]
 527     */
 528     sal_Bool            bOut;
 529 } typelib_Parameter_Init;
 530
 531 /** Init struct of union types for typelib_typedescription_newUnion().
 532 */
 533 typedef struct _typelib_Union_Init
 534 {
 535     /** union member discriminant
 536     */
 537     sal_Int64           nDiscriminant;
 538     /** union member name
 539     */
 540     rtl_uString *       pMemberName;
 541     /** union member type
 542     */
 543     typelib_TypeDescriptionReference* pTypeRef;
 544 } typelib_Union_Init;
 545
 546 #if defined( SAL_W32)
 547 #pragma pack(pop)
 548 #endif
 549
 550
 551 /** Creates a union type description. All discriminants are handled as int64 values.
 552     The pDiscriminantTypeRef must be of type byte, short, ..., up to hyper.
 553
 554     @param ppRet inout union type description
 555     @param pTypeName name of union type
 556     @param pDiscriminantTypeRef discriminant type
 557     @param nDefaultDiscriminant default discriminant
 558     @param pDefaultTypeRef default value type of union
 559     @param nMembers number of union members
 560     @param pMembers init members
 561 */
 562 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newUnion(
 563     typelib_TypeDescription ** ppRet,
 564     rtl_uString * pTypeName,
 565     typelib_TypeDescriptionReference * pDiscriminantTypeRef,
 566     sal_Int64 nDefaultDiscriminant,
 567     typelib_TypeDescriptionReference * pDefaultTypeRef,
 568     sal_Int32 nMembers,
 569     typelib_Union_Init * pMembers )
 570     SAL_THROW_EXTERN_C();
 571
 572 /** Creates an enum type description.
 573
 574     @param ppRet inout enum type description
 575     @param pTypeName name of enum
 576     @param nDefaultValue default enum value
 577     @param nEnumValues number of enum values
 578     @param ppEnumNames names of enum values
 579     @param pEnumValues enum values
 580 */
 581 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newEnum(
 582     typelib_TypeDescription ** ppRet,
 583     rtl_uString * pTypeName,
 584     sal_Int32 nDefaultValue,
 585     sal_Int32 nEnumValues,
 586     rtl_uString ** ppEnumNames,
 587     sal_Int32 * pEnumValues )
 588     SAL_THROW_EXTERN_C();
 589
 590 /** Creates an array type description.
 591
 592     @param ppRet inout enum type description
 593     @param pElementTypeRef element type
 594     @param nDimensions number of dimensions
 595     @param pDimensions dimensions
 596 */
 597 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newArray(
 598     typelib_TypeDescription ** ppRet,
 599     typelib_TypeDescriptionReference * pElementTypeRef,
 600     sal_Int32 nDimensions,
 601     sal_Int32 * pDimensions )
 602     SAL_THROW_EXTERN_C ();
 603
 604 /** Creates a new type description.
 605
 606     Since this function can only be used to create type descriptions for plain
 607     struct types, not for instantiated polymorphic struct types, the function
 608     typelib_typedescription_newStruct should be used instead for all struct
 609     types.
 610
 611     @param ppRet inout type description
 612     @param eTypeClass type class
 613     @param pTypeName name of type
 614     @param pType sequence, array: element type;
 615                  struct, Exception: base type;
 616     @param nMembers number of members if struct, exception
 617     @param pMembers array of members if struct, exception
 618 */
 619 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_new(
 620     typelib_TypeDescription ** ppRet,
 621     typelib_TypeClass eTypeClass,
 622     rtl_uString * pTypeName,
 623     typelib_TypeDescriptionReference * pType,
 624     sal_Int32 nMembers,
 625     typelib_CompoundMember_Init * pMembers )
 626     SAL_THROW_EXTERN_C();
 627
 628 /** Creates a new struct type description.
 629
 630     @param ppRet inout type description
 631     @param pTypeName name of type
 632     @param pType base type;
 633     @param nMembers number of members
 634     @param pMembers array of members
 635
 636     @since UDK 3.2.0
 637 */
 638 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newStruct(
 639     typelib_TypeDescription ** ppRet,
 640     rtl_uString * pTypeName,
 641     typelib_TypeDescriptionReference * pType,
 642     sal_Int32 nMembers,
 643     typelib_StructMember_Init * pMembers )
 644     SAL_THROW_EXTERN_C();
 645
 646 /** Creates an interface type description.
 647
 648     @param ppRet inout interface type description
 649     @param pTypeName the fully qualified name of the interface.
 650     @param nUik1 uik part
 651     @param nUik2 uik part
 652     @param nUik3 uik part
 653     @param nUik4 uik part
 654     @param nUik5 uik part
 655     @param pBaseInterface base interface type, else 0
 656     @param nMembers number of members
 657     @param ppMembers members; attributes or methods
 658
 659     @deprecated
 660     use typelib_typedescription_newMIInterface instead
 661 */
 662 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newInterface(
 663     typelib_InterfaceTypeDescription ** ppRet,
 664     rtl_uString * pTypeName,
 665     sal_uInt32 nUik1, sal_uInt16 nUik2, sal_uInt16 nUik3, sal_uInt32 nUik4, sal_uInt32 nUik5,
 666     typelib_TypeDescriptionReference * pBaseInterface,
 667     sal_Int32 nMembers,
 668     typelib_TypeDescriptionReference ** ppMembers )
 669     SAL_THROW_EXTERN_C();
 670
 671 /** Creates a multiple-inheritance interface type description.
 672
 673     @param ppRet inout interface type description
 674     @param pTypeName the fully qualified name of the interface.
 675     @param nUik1 uik part
 676     @param nUik2 uik part
 677     @param nUik3 uik part
 678     @param nUik4 uik part
 679     @param nUik5 uik part
 680     @param nBaseInterfaces number of base interface types
 681     @param ppBaseInterfaces base interface types
 682     @param nMembers number of members
 683     @param ppMembers members; attributes or methods
 684
 685     @since UDK 3.2.0
 686 */
 687 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newMIInterface(
 688     typelib_InterfaceTypeDescription ** ppRet,
 689     rtl_uString * pTypeName,
 690     sal_uInt32 nUik1, sal_uInt16 nUik2, sal_uInt16 nUik3, sal_uInt32 nUik4, sal_uInt32 nUik5,
 691     sal_Int32 nBaseInterfaces,
 692     typelib_TypeDescriptionReference ** ppBaseInterfaces,
 693     sal_Int32 nMembers,
 694     typelib_TypeDescriptionReference ** ppMembers )
 695     SAL_THROW_EXTERN_C();
 696
 697 /** Creates an interface method type description.
 698
 699     @param ppRet inout method type description
 700     @param nAbsolutePosition position of member including all members of base interfaces
 701     @param bOneWay determines whether method is declared oneway
 702     @param pMethodName fully qualified name of method including interface name
 703     @param eReturnTypeClass type class of return type
 704     @param pReturnTypeName type name of the return type
 705     @param nParams number of parameters
 706     @param pParams parameter types
 707     @param nExceptions number of exceptions
 708     @param ppExceptionNames type names of exceptions
 709 */
 710 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newInterfaceMethod(
 711     typelib_InterfaceMethodTypeDescription ** ppRet,
 712     sal_Int32 nAbsolutePosition,
 713     sal_Bool bOneWay,
 714     rtl_uString * pMethodName,
 715     typelib_TypeClass eReturnTypeClass,
 716     rtl_uString * pReturnTypeName,
 717     sal_Int32 nParams,
 718     typelib_Parameter_Init * pParams,
 719     sal_Int32 nExceptions,
 720     rtl_uString ** ppExceptionNames )
 721     SAL_THROW_EXTERN_C();
 722
 723 /** Creates an interface attribute type description.
 724
 725     @param ppRet inout attribute type description
 726     @param nAbsolutePosition position of this attribute including all members of base interfaces
 727     @param pAttributeName fully qualified name of attribute including interface
 728     name
 729     @param eAttributeTypeClass type class of attribute type
 730     @param pAttributeTypeName type name of attribute type
 731     @param bReadOnly determines whether attribute is read-only
 732
 733     @deprecated
 734     use typelib_typedescription_newExtendedInterfaceAttribute instead
 735 */
 736 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newInterfaceAttribute(
 737     typelib_InterfaceAttributeTypeDescription ** ppRet,
 738     sal_Int32 nAbsolutePosition,
 739     rtl_uString * pAttributeName,
 740     typelib_TypeClass eAttributeTypeClass,
 741     rtl_uString * pAttributeTypeName,
 742     sal_Bool bReadOnly )
 743     SAL_THROW_EXTERN_C();
 744
 745 /** Creates an extended interface attribute type description.
 746
 747     @param ppRet inout attribute type description
 748     @param nAbsolutePosition position of this attribute including all members of
 749     base interfaces
 750     @param pAttributeName fully qualified name of attribute including interface
 751     name
 752     @param eAttributeTypeClass type class of attribute type
 753     @param pAttributeTypeName type name of attribute type
 754     @param bReadOnly determines whether attribute is read-only
 755     @param nGetExceptions number of getter exceptions
 756     @param ppGetExceptionNames type names of getter exceptions
 757     @param nSetExceptions number of setter exceptions
 758     @param ppSetExceptionNames type names of setter exceptions
 759
 760     @since UDK 3.2.0
 761 */
 762 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_newExtendedInterfaceAttribute(
 763     typelib_InterfaceAttributeTypeDescription ** ppRet,
 764     sal_Int32 nAbsolutePosition,
 765     rtl_uString * pAttributeName,
 766     typelib_TypeClass eAttributeTypeClass,
 767     rtl_uString * pAttributeTypeName,
 768     sal_Bool bReadOnly,
 769     sal_Int32 nGetExceptions, rtl_uString ** ppGetExceptionNames,
 770     sal_Int32 nSetExceptions, rtl_uString ** ppSetExceptionNames )
 771     SAL_THROW_EXTERN_C();
 772
 773 /** Increments reference count of given type description.
 774
 775     @param pDesc type description
 776 */
 777 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_acquire(
 778     typelib_TypeDescription * pDesc )
 779     SAL_THROW_EXTERN_C();
 780
 781 /** Decrements reference count of given type. If reference count reaches 0, the trype description
 782     is deleted.
 783
 784     @param pDesc type description
 785 */
 786 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_release(
 787     typelib_TypeDescription * pDesc )
 788     SAL_THROW_EXTERN_C();
 789
 790 /** Registers a type description and creates a type description reference. Type descriptions
 791     will be registered automatically if they are provided via the callback chain.
 792
 793     @param ppNewDescription inout description to be registered;
 794 */
 795 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_register(
 796     typelib_TypeDescription ** ppNewDescription )
 797     SAL_THROW_EXTERN_C();
 798
 799 /** Tests whether two types descriptions are equal, i.e. type class and names are equal.
 800
 801     @param p1 a type description
 802     @param p2 another type description
 803     @return true, if type descriptions are equal
 804 */
 805 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescription_equals(
 806     const typelib_TypeDescription * p1, const typelib_TypeDescription * p2 )
 807     SAL_THROW_EXTERN_C();
 808
 809 /** Retrieves a type description via its fully qualified name.
 810
 811     @param ppRet inout type description; *ppRet is 0, if type description was not found
 812     @param pName name demanded type description
 813 */
 814 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_getByName(
 815     typelib_TypeDescription ** ppRet, rtl_uString * pName )
 816     SAL_THROW_EXTERN_C();
 817
 818 /** Sets size of type description cache.
 819
 820     @param nNewSize new size of cache
 821 */
 822 CPPU_DLLPUBLIC void SAL_CALL typelib_setCacheSize(
 823     sal_Int32 nNewSize )
 824     SAL_THROW_EXTERN_C();
 825
 826 /** Function pointer declaration of callback function get additional descriptions. Callbacks
 827     must provide complete type descriptions (see typelib_typedescription_complete())!
 828
 829     @param pContext callback context
 830     @param ppRet inout type description
 831     @param pTypeName  name of demanded type description
 832 */
 833 typedef void (SAL_CALL * typelib_typedescription_Callback)(
 834     void * pContext, typelib_TypeDescription ** ppRet, rtl_uString * pTypeName );
 835
 836 /** Registers callback function providing additional type descriptions.
 837
 838     @param pContext callback context
 839     @param pCallback callback function
 840 */
 841 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_registerCallback(
 842     void * pContext, typelib_typedescription_Callback pCallback )
 843     SAL_THROW_EXTERN_C();
 844
 845 /** Revokes a previously registered callback function.
 846
 847     @param pContext callback context
 848     @param pCallback registered callback function
 849 */
 850 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescription_revokeCallback(
 851     void * pContext, typelib_typedescription_Callback pCallback )
 852     SAL_THROW_EXTERN_C();
 853
 854
 855 /*----------------------------------------------------------------------------*/
 856 /*----------------------------------------------------------------------------*/
 857 /*----------------------------------------------------------------------------*/
 858
 859 /// @cond INTERNAL
 860
 861 /** Returns true, if the type description reference may lose the type description. Otherwise
 862     pType is a valid pointer and cannot be discarded through the lifetime of this reference.
 863     Remark: If the pWeakObj of the type is set too, you can avoid the call of
 864     ...getDescription(...) and use the description directly. pWeakObj == 0 means, that the
 865     description is not initialized.
 866 */
 867 #define TYPELIB_TYPEDESCRIPTIONREFERENCE_ISREALLYWEAK( eTypeClass ) \
 868     ((eTypeClass) == typelib_TypeClass_INTERFACE_METHOD || \
 869      (eTypeClass) == typelib_TypeClass_INTERFACE_ATTRIBUTE)
 870
 871 /** Gets a description from the reference. The description may not be locked by this call.
 872     You must use the TYPELIB_DANGER_RELEASE macro to release the description fetched with
 873     this macro.
 874 */
 875 #define TYPELIB_DANGER_GET( ppDescription, pTypeRef ) \
 876 { \
 877     typelib_TypeDescriptionReference * pMacroTypeRef = (pTypeRef); \
 878     typelib_TypeDescription ** ppMacroTypeDescr = (ppDescription); \
 879     if (TYPELIB_TYPEDESCRIPTIONREFERENCE_ISREALLYWEAK( pMacroTypeRef->eTypeClass )) \
 880     { \
 881         typelib_typedescriptionreference_getDescription( ppMacroTypeDescr, pMacroTypeRef ); \
 882     } \
 883     else if (!pMacroTypeRef->pType || !pMacroTypeRef->pType->pWeakRef) \
 884     { \
 885         typelib_typedescriptionreference_getDescription( ppMacroTypeDescr, pMacroTypeRef ); \
 886         if (*ppMacroTypeDescr) \
 887             typelib_typedescription_release( *ppMacroTypeDescr ); \
 888     } \
 889     else \
 890     { \
 891         *ppMacroTypeDescr = pMacroTypeRef->pType; \
 892     } \
 893 }
 894
 895 /** Releases the description previouse fetched by TYPELIB_DANGER_GET.
 896 */
 897 #define TYPELIB_DANGER_RELEASE( pDescription ) \
 898 { \
 899     if (TYPELIB_TYPEDESCRIPTIONREFERENCE_ISREALLYWEAK( (pDescription)->eTypeClass )) \
 900         typelib_typedescription_release( pDescription ); \
 901 }
 902
 903 /// @endcond
 904
 905 /** Creates a type description reference. This is a weak reference not holding the description.
 906     If the description is already registered, the previous one is returned.
 907
 908     @param ppTDR inout type description reference
 909     @param eTypeClass type class of type
 910     @param pTypeName name of type
 911 */
 912 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_new(
 913     typelib_TypeDescriptionReference ** ppTDR,
 914     typelib_TypeClass eTypeClass,
 915     rtl_uString * pTypeName )
 916     SAL_THROW_EXTERN_C();
 917
 918 /** Creates a type description reference. This is a weak reference not holding the description.
 919     If the description is already registered, the previous one is returned.
 920
 921     @param ppTDR inout type description reference
 922     @param eTypeClass type class of type
 923     @param pTypeName ascii name of type
 924 */
 925 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_newByAsciiName(
 926     typelib_TypeDescriptionReference ** ppTDR,
 927     typelib_TypeClass eTypeClass,
 928     const sal_Char * pTypeName )
 929     SAL_THROW_EXTERN_C();
 930
 931 /** Increments reference count of type description reference.
 932
 933     @param pRef type description reference
 934 */
 935 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_acquire(
 936     typelib_TypeDescriptionReference * pRef )
 937     SAL_THROW_EXTERN_C();
 938
 939 /** Increments reference count of type description reference. If the reference count reaches 0,
 940     then the reference is deleted.
 941
 942     @param pRef type description reference
 943 */
 944 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_release(
 945     typelib_TypeDescriptionReference * pRef )
 946     SAL_THROW_EXTERN_C();
 947
 948 /** Retrieves the type description for a given reference. If it is not possible to resolve the
 949     reference, null is returned.
 950
 951     @param[in,out] ppRet type description
 952     @param[in] pRef type description reference
 953 */
 954 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_getDescription(
 955     typelib_TypeDescription ** ppRet, typelib_TypeDescriptionReference * pRef )
 956     SAL_THROW_EXTERN_C();
 957
 958 /** Tests whether two types description references are equal, i.e. type class and names are equal.
 959
 960     @param p1 a type description reference
 961     @param p2 another type description reference
 962     @return true, if type description references are equal
 963 */
 964 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescriptionreference_equals(
 965     const typelib_TypeDescriptionReference * p1, const typelib_TypeDescriptionReference * p2 )
 966     SAL_THROW_EXTERN_C();
 967
 968 /** Assigns a type.
 969
 970     @param ppDest destination type
 971     @param pSource source type
 972 */
 973 CPPU_DLLPUBLIC void SAL_CALL typelib_typedescriptionreference_assign(
 974     typelib_TypeDescriptionReference ** ppDest,
 975     typelib_TypeDescriptionReference * pSource )
 976     SAL_THROW_EXTERN_C();
 977
 978 /** Tests if values of type pAssignable can be assigned by values of type pFrom. This includes
 979     widening conversion (e.g., long assignable from short), as long as there is no data loss.
 980
 981     @param pAssignable type description of value to be assigned
 982     @param pFrom type description of value
 983 */
 984 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescription_isAssignableFrom(
 985     typelib_TypeDescription * pAssignable,
 986     typelib_TypeDescription * pFrom )
 987     SAL_THROW_EXTERN_C();
 988
 989 /** Tests if values of type pAssignable can be assigned by values of type pFrom. This includes
 990     widening conversion (e.g., long assignable from short), as long as there is no data loss.
 991
 992     @param pAssignable type of value to be assigned
 993     @param pFrom type of value
 994 */
 995 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescriptionreference_isAssignableFrom(
 996     typelib_TypeDescriptionReference * pAssignable,
 997     typelib_TypeDescriptionReference * pFrom )
 998     SAL_THROW_EXTERN_C();
 999
1000 /** Gets static type reference of standard types by type class.
1001     ADDITIONAL OPT: provides Type com.sun.star.uno.Exception for typelib_TypeClass_EXCEPTION
1002                     and com.sun.star.uno.XInterface for typelib_TypeClass_INTERFACE.
1003
1004     Thread synchronizes on typelib mutex.
1005
1006     @param eTypeClass type class of basic type
1007     @return pointer to type reference pointer
1008 */
1009 CPPU_DLLPUBLIC typelib_TypeDescriptionReference ** SAL_CALL typelib_static_type_getByTypeClass(
1010     typelib_TypeClass eTypeClass )
1011     SAL_THROW_EXTERN_C();
1012
1013 /** Inits static type reference. Thread synchronizes on typelib init mutex.
1014
1015     @param ppRef pointer to type reference pointer
1016     @param eTypeClass type class of type
1017     @param pTypeName ascii name of type
1018 */
1019 CPPU_DLLPUBLIC void SAL_CALL typelib_static_type_init(
1020     typelib_TypeDescriptionReference ** ppRef,
1021     typelib_TypeClass eTypeClass, const sal_Char * pTypeName )
1022     SAL_THROW_EXTERN_C();
1023
1024 /** Inits static sequence type reference. Thread synchronizes on typelib init mutex.
1025
1026     @param ppRef pointer to type reference pointer
1027     @param pElementType element type of sequence
1028 */
1029 CPPU_DLLPUBLIC void SAL_CALL typelib_static_sequence_type_init(
1030     typelib_TypeDescriptionReference ** ppRef,
1031     typelib_TypeDescriptionReference * pElementType )
1032     SAL_THROW_EXTERN_C ();
1033
1034 /** Inits static array type reference. Thread synchronizes on typelib init mutex.
1035
1036     @param ppRef pointer to type reference pointer
1037     @param pElementType element type of sequence
1038     @param nDimensions number of dimensions
1039     @param ... additional sal_Int32 parameter for each dimension
1040 */
1041 CPPU_DLLPUBLIC void SAL_CALL typelib_static_array_type_init(
1042     typelib_TypeDescriptionReference ** ppRef,
1043     typelib_TypeDescriptionReference * pElementType,
1044     sal_Int32 nDimensions, ... )
1045     SAL_THROW_EXTERN_C ();
1046
1047 /** Inits incomplete static compound type reference. Thread synchronizes on typelib init mutex.
1048
1049     Since this function can only be used to create type descriptions for plain
1050     struct types, not for instantiated polymorphic struct types, the function
1051     typelib_static_struct_type_init should be used instead for all struct types.
1052
1053     @param ppRef pointer to type reference pointer
1054     @param eTypeClass typelib_TypeClass_STRUCT or typelib_TypeClass_EXCEPTION
1055     @param pTypeName name of type
1056     @param pBaseType base type
1057     @param nMembers number of members
1058     @param ppMembers member types
1059 */
1060 CPPU_DLLPUBLIC void SAL_CALL typelib_static_compound_type_init(
1061     typelib_TypeDescriptionReference ** ppRef,
1062     typelib_TypeClass eTypeClass, const sal_Char * pTypeName,
1063     typelib_TypeDescriptionReference * pBaseType,
1064     sal_Int32 nMembers, typelib_TypeDescriptionReference ** ppMembers )
1065     SAL_THROW_EXTERN_C();
1066
1067 /** Inits incomplete static struct type reference.
1068
1069     Thread synchronizes on typelib init mutex.
1070
1071     @param ppRef pointer to type reference pointer
1072     @param pTypeName name of type
1073     @param pBaseType base type
1074     @param nMembers number of members
1075     @param ppMembers member types
1076     @param pParameterizedTypes flags for direct members, specifying whether they
1077         are of parameterized type (true) or explict type (false); must be null
1078         for a plain struct type
1079
1080     @since UDK 3.2.0
1081 */
1082 CPPU_DLLPUBLIC void SAL_CALL typelib_static_struct_type_init(
1083     typelib_TypeDescriptionReference ** ppRef, const sal_Char * pTypeName,
1084     typelib_TypeDescriptionReference * pBaseType,
1085     sal_Int32 nMembers, typelib_TypeDescriptionReference ** ppMembers,
1086     sal_Bool const * pParameterizedTypes )
1087     SAL_THROW_EXTERN_C();
1088
1089 /** Inits incomplete static interface type reference. Thread synchronizes on typelib init mutex.
1090
1091     @param ppRef pointer to type reference pointer
1092     @param pTypeName name of interface
1093     @param pBaseType base type
1094 */
1095 CPPU_DLLPUBLIC void SAL_CALL typelib_static_interface_type_init(
1096     typelib_TypeDescriptionReference ** ppRef,
1097     const sal_Char * pTypeName,
1098     typelib_TypeDescriptionReference * pBaseType )
1099     SAL_THROW_EXTERN_C();
1100
1101 /** Inits incomplete static multiple-inheritance interface type reference.
1102     Thread synchronizes on typelib init mutex.
1103
1104     @param ppRef pointer to type reference pointer
1105     @param pTypeName name of interface
1106     @param nBaseTypes number of base types
1107     @param ppBaseTypes base types
1108
1109     @since UDK 3.2.0
1110 */
1111 CPPU_DLLPUBLIC void SAL_CALL typelib_static_mi_interface_type_init(
1112     typelib_TypeDescriptionReference ** ppRef,
1113     const sal_Char * pTypeName,
1114     sal_Int32 nBaseTypes,
1115     typelib_TypeDescriptionReference ** ppBaseTypes )
1116     SAL_THROW_EXTERN_C();
1117
1118 /** Inits incomplete static enum type reference. Thread synchronizes on typelib init mutex.
1119
1120     @param ppRef pointer to type reference pointer
1121     @param pTypeName name of enum
1122     @param nDefaultValue default enum value
1123 */
1124 CPPU_DLLPUBLIC void SAL_CALL typelib_static_enum_type_init(
1125     typelib_TypeDescriptionReference ** ppRef,
1126     const sal_Char * pTypeName,
1127     sal_Int32 nDefaultValue )
1128     SAL_THROW_EXTERN_C();
1129
1130 /** Completes a typedescription to be used for, e.g., marshalling values. COMPOUND, UNION,
1131     INTERFACE and ENUM type descriptions may be partly initialized (see typelib_static_...(),
1132     typelib_TypeDescription::bComplete). For interface type descriptions, this will also
1133     init index tables.
1134
1135     @param ppTypeDescr [inout] type description to be completed (may be exchanged!)
1136     @return true, if type description is complete
1137 */
1138 CPPU_DLLPUBLIC sal_Bool SAL_CALL typelib_typedescription_complete(
1139     typelib_TypeDescription ** ppTypeDescr )
1140     SAL_THROW_EXTERN_C();
1141
1142 #ifdef __cplusplus
1143 }
1144 #endif
1145
1146 #endif
1147
1148 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */