cppu/inc/uno/mapping.h

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: mapping.h,v $
  10  * $Revision: 1.10 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef _UNO_MAPPING_H_
  31 #define _UNO_MAPPING_H_
  32
  33 #include <sal/types.h>
  34 #include <rtl/ustring.h>
  35
  36
  37 #ifdef __cplusplus
  38 extern "C"
  39 {
  40 #endif
  41
  42 struct _typelib_InterfaceTypeDescription;
  43 struct _uno_Mapping;
  44 struct _uno_Environment;
  45
  46 /**
  47    Function pointer declaration to acquire a UNO mapping.
  48 */
  49 typedef void (SAL_CALL * uno_AcquireMappingFunc)(struct _uno_Mapping *);
  50
  51 /**
  52    Function pointer declaration to release a UNO mapping.
  53 */
  54 typedef void (SAL_CALL * uno_ReleaseMappingFunc)(struct _uno_Mapping *);
  55
  56 /** Function pointer declaration to map an interface from one environment to another.
  57
  58     @param pMapping                     mapping
  59     @param ppOut                        [inout] destination interface; existing interfaces are released
  60     @param pInterface           source interface
  61     @param pInterfaceTypeDescr type description of the interface
  62 */
  63 typedef void (SAL_CALL * uno_MapInterfaceFunc)(
  64     struct _uno_Mapping * pMapping,
  65     void ** ppOut, void * pInterface,
  66     struct _typelib_InterfaceTypeDescription * pInterfaceTypeDescr );
  67
  68
  69 #if defined( SAL_W32)
  70 #pragma pack(push, 8)
  71 #elif defined(SAL_OS2)
  72 #pragma pack(push, 8)
  73 #endif
  74
  75 /** This is the binary specification of a mapping.
  76 */
  77 typedef struct _uno_Mapping
  78 {
  79     /** Acquires mapping
  80     */
  81     uno_AcquireMappingFunc acquire;
  82
  83     /** Releases mapping. The last release may unload bridges.
  84     */
  85     uno_ReleaseMappingFunc release;
  86
  87     /** mapping function
  88     */
  89     uno_MapInterfaceFunc mapInterface;
  90 } uno_Mapping;
  91
  92 #if defined( SAL_W32) ||  defined(SAL_OS2)
  93 #pragma pack(pop)
  94 #endif
  95
  96 /** Gets an interface mapping from one environment to another.
  97
  98     @param ppMapping    [inout] mapping; existing mapping will be released
  99     @param pFrom                source environment
 100     @param pTo                  destination environment
 101                         (interfaces resulting in mapInterface() call can be used
 102                         in this language environment)
 103     @param pAddPurpose  additional purpose of mapping (e.g., protocolling); defaults to 0 (none)
 104 */
 105 void SAL_CALL uno_getMapping(
 106     struct _uno_Mapping ** ppMapping,
 107     struct _uno_Environment * pFrom,
 108     struct _uno_Environment * pTo,
 109     rtl_uString * pAddPurpose )
 110     SAL_THROW_EXTERN_C();
 111
 112 /** Callback function pointer declaration to get a mapping.
 113
 114     @param ppMapping    inout mapping
 115     @param pFrom                source environment
 116     @param pTo                  destination environment
 117     @param pAddPurpose  additional purpose
 118 */
 119 typedef void (SAL_CALL * uno_getMappingFunc)(
 120     struct _uno_Mapping ** ppMapping,
 121     struct _uno_Environment * pFrom,
 122     struct _uno_Environment * pTo,
 123     rtl_uString * pAddPurpose );
 124
 125 /** Registers a callback being called each time a mapping is demanded.
 126
 127     @param pCallback    callback function
 128 */
 129 void SAL_CALL uno_registerMappingCallback(
 130     uno_getMappingFunc pCallback )
 131     SAL_THROW_EXTERN_C();
 132
 133 /** Revokes a mapping callback registration.
 134
 135     @param pCallback    callback function
 136 */
 137 void SAL_CALL uno_revokeMappingCallback(
 138     uno_getMappingFunc pCallback )
 139     SAL_THROW_EXTERN_C();
 140
 141 /** Function pointer declaration to free a mapping.
 142
 143     @param pMapping             mapping to be freed
 144 */
 145 typedef void (SAL_CALL * uno_freeMappingFunc)( struct _uno_Mapping * pMapping );
 146
 147 /** Registers a mapping. A mapping registers itself on first acquire and revokes itself on last
 148     release. The given freeMapping function is called by the runtime to cleanup any resources.
 149
 150     @param ppMapping    inout mapping to be registered
 151     @param freeMapping  called by runtime to delete mapping
 152     @param pFrom                source environment
 153     @param pTo                  destination environment
 154     @param pAddPurpose  additional purpose string; defaults to 0
 155 */
 156 void SAL_CALL uno_registerMapping(
 157     struct _uno_Mapping ** ppMapping, uno_freeMappingFunc freeMapping,
 158     struct _uno_Environment * pFrom, struct _uno_Environment * pTo, rtl_uString * pAddPurpose )
 159     SAL_THROW_EXTERN_C();
 160
 161 /** Revokes a mapping. A mapping registers itself on first acquire and revokes itself on last
 162     release.
 163
 164     @param pMapping             mapping to be revoked
 165 */
 166 void SAL_CALL uno_revokeMapping(
 167     struct _uno_Mapping * pMapping )
 168     SAL_THROW_EXTERN_C();
 169
 170 /** Gets an interface mapping from one language environment to another by corresponding environment
 171     type names.
 172
 173     @param ppMapping    [inout] mapping; existing mapping will be released
 174     @param pFrom                source environment type name
 175     @param pTo                  destination environment type name
 176                         (interfaces resulting in mapInterface() call can be used
 177                         in this language environment)
 178     @param pAddPurpose  additional purpose of mapping (e.g., protocolling); defaults to 0 (none)
 179 */
 180 void SAL_CALL uno_getMappingByName(
 181     struct _uno_Mapping ** ppMapping,
 182     rtl_uString * pFrom,
 183     rtl_uString * pTo,
 184     rtl_uString * pAddPurpose )
 185     SAL_THROW_EXTERN_C();
 186
 187 /* symbol exported by each language binding library */
 188 #define UNO_EXT_GETMAPPING "uno_ext_getMapping"
 189
 190 /** Function pointer declaration to get a mapping from a loaded bridge. Bridges export a function
 191     called uno_ext_getMapping() of this signature.
 192
 193     @param ppMapping    [inout] mapping; existing mapping will be released
 194     @pFrom                              source environment
 195     @pTo                                destination environment
 196 */
 197 typedef void (SAL_CALL * uno_ext_getMappingFunc)(
 198     struct _uno_Mapping ** ppMapping,
 199     struct _uno_Environment * pFrom,
 200     struct _uno_Environment * pTo );
 201
 202 #ifdef __cplusplus
 203 }
 204 #endif
 205
 206 #endif