cppu/inc/uno/mapping.h

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