xref: /trunk/main/cppu/inc/uno/mapping.h (revision 24f6443d)
1 /**************************************************************
2  *
3  * Licensed to the Apache Software Foundation (ASF) under one
4  * or more contributor license agreements.  See the NOTICE file
5  * distributed with this work for additional information
6  * regarding copyright ownership.  The ASF licenses this file
7  * to you under the Apache License, Version 2.0 (the
8  * "License"); you may not use this file except in compliance
9  * with the License.  You may obtain a copy of the License at
10  *
11  *   http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing,
14  * software distributed under the License is distributed on an
15  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16  * KIND, either express or implied.  See the License for the
17  * specific language governing permissions and limitations
18  * under the License.
19  *
20  *************************************************************/
21 
22 
23 #ifndef _UNO_MAPPING_H_
24 #define _UNO_MAPPING_H_
25 
26 #include <sal/types.h>
27 #include <rtl/ustring.h>
28 
29 
30 #ifdef __cplusplus
31 extern "C"
32 {
33 #endif
34 
35 struct _typelib_InterfaceTypeDescription;
36 struct _uno_Mapping;
37 struct _uno_Environment;
38 
39 /**
40    Function pointer declaration to acquire a UNO mapping.
41 */
42 typedef void (SAL_CALL * uno_AcquireMappingFunc)(struct _uno_Mapping *);
43 
44 /**
45    Function pointer declaration to release a UNO mapping.
46 */
47 typedef void (SAL_CALL * uno_ReleaseMappingFunc)(struct _uno_Mapping *);
48 
49 /** Function pointer declaration to map an interface from one environment to another.
50 
51 	@param pMapping			mapping
52 	@param ppOut			[inout] destination interface; existing interfaces are released
53 	@param pInterface		source interface
54 	@param pInterfaceTypeDescr type description of the interface
55 */
56 typedef void (SAL_CALL * uno_MapInterfaceFunc)(
57 	struct _uno_Mapping * pMapping,
58 	void ** ppOut, void * pInterface,
59 	struct _typelib_InterfaceTypeDescription * pInterfaceTypeDescr );
60 
61 
62 #if defined( SAL_W32)
63 #pragma pack(push, 8)
64 #elif defined(SAL_OS2)
65 #pragma pack(push, 8)
66 #endif
67 
68 /** This is the binary specification of a mapping.
69 */
70 typedef struct _uno_Mapping
71 {
72 	/** Acquires mapping
73 	*/
74 	uno_AcquireMappingFunc acquire;
75 
76 	/** Releases mapping. The last release may unload bridges.
77 	*/
78 	uno_ReleaseMappingFunc release;
79 
80 	/** mapping function
81 	*/
82 	uno_MapInterfaceFunc mapInterface;
83 } uno_Mapping;
84 
85 #if defined( SAL_W32) ||  defined(SAL_OS2)
86 #pragma pack(pop)
87 #endif
88 
89 /** Gets an interface mapping from one environment to another.
90 
91 	@param ppMapping	[inout] mapping; existing mapping will be released
92 	@param pFrom		source environment
93 	@param pTo			destination environment
94 						(interfaces resulting in mapInterface() call can be used
95 						in this language environment)
96 	@param pAddPurpose	additional purpose of mapping (e.g., protocolling); defaults to 0 (none)
97 */
98 void SAL_CALL uno_getMapping(
99 	struct _uno_Mapping ** ppMapping,
100 	struct _uno_Environment * pFrom,
101 	struct _uno_Environment * pTo,
102 	rtl_uString * pAddPurpose )
103 	SAL_THROW_EXTERN_C();
104 
105 /** Callback function pointer declaration to get a mapping.
106 
107 	@param ppMapping	inout mapping
108 	@param pFrom		source environment
109 	@param pTo			destination environment
110 	@param pAddPurpose	additional purpose
111 */
112 typedef void (SAL_CALL * uno_getMappingFunc)(
113 	struct _uno_Mapping ** ppMapping,
114 	struct _uno_Environment * pFrom,
115 	struct _uno_Environment * pTo,
116 	rtl_uString * pAddPurpose );
117 
118 /** Registers a callback being called each time a mapping is demanded.
119 
120 	@param pCallback	callback function
121 */
122 void SAL_CALL uno_registerMappingCallback(
123 	uno_getMappingFunc pCallback )
124 	SAL_THROW_EXTERN_C();
125 
126 /** Revokes a mapping callback registration.
127 
128 	@param pCallback	callback function
129 */
130 void SAL_CALL uno_revokeMappingCallback(
131 	uno_getMappingFunc pCallback )
132 	SAL_THROW_EXTERN_C();
133 
134 /** Function pointer declaration to free a mapping.
135 
136 	@param pMapping		mapping to be freed
137 */
138 typedef void (SAL_CALL * uno_freeMappingFunc)( struct _uno_Mapping * pMapping );
139 
140 /** Registers a mapping. A mapping registers itself on first acquire and revokes itself on last
141     release. The given freeMapping function is called by the runtime to cleanup any resources.
142 
143 	@param ppMapping	inout mapping to be registered
144 	@param freeMapping	called by runtime to delete mapping
145 	@param pFrom		source environment
146 	@param pTo			destination environment
147 	@param pAddPurpose	additional purpose string; defaults to 0
148 */
149 void SAL_CALL uno_registerMapping(
150 	struct _uno_Mapping ** ppMapping, uno_freeMappingFunc freeMapping,
151 	struct _uno_Environment * pFrom, struct _uno_Environment * pTo, rtl_uString * pAddPurpose )
152 	SAL_THROW_EXTERN_C();
153 
154 /** Revokes a mapping. A mapping registers itself on first acquire and revokes itself on last
155     release.
156 
157 	@param pMapping		mapping to be revoked
158 */
159 void SAL_CALL uno_revokeMapping(
160 	struct _uno_Mapping * pMapping )
161 	SAL_THROW_EXTERN_C();
162 
163 /** Gets an interface mapping from one language environment to another by corresponding environment
164     type names.
165 
166 	@param ppMapping	[inout] mapping; existing mapping will be released
167 	@param pFrom		source environment type name
168 	@param pTo			destination environment type name
169 						(interfaces resulting in mapInterface() call can be used
170 						in this language environment)
171 	@param pAddPurpose	additional purpose of mapping (e.g., protocolling); defaults to 0 (none)
172 */
173 void SAL_CALL uno_getMappingByName(
174 	struct _uno_Mapping ** ppMapping,
175 	rtl_uString * pFrom,
176 	rtl_uString * pTo,
177 	rtl_uString * pAddPurpose )
178 	SAL_THROW_EXTERN_C();
179 
180 /* symbol exported by each language binding library */
181 #define UNO_EXT_GETMAPPING "uno_ext_getMapping"
182 
183 /** Function pointer declaration to get a mapping from a loaded bridge. Bridges export a function
184     called uno_ext_getMapping() of this signature.
185 
186 	@param ppMapping	[inout] mapping; existing mapping will be released
187 	@pFrom				source environment
188 	@pTo				destination environment
189 */
190 typedef void (SAL_CALL * uno_ext_getMappingFunc)(
191 	struct _uno_Mapping ** ppMapping,
192 	struct _uno_Environment * pFrom,
193 	struct _uno_Environment * pTo );
194 
195 #ifdef __cplusplus
196 }
197 #endif
198 
199 #endif
200