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