epoc32/include/stdapis/openssl/dso.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
parent 0 061f57f2323e
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     1 /* dso.h -*- mode:C; c-file-style: "eay" -*- */
     2 /* Written by Geoff Thorpe (geoff@geoffthorpe.net) for the OpenSSL
     3  * project 2000.
     4  */
     5 /* ====================================================================
     6  * Copyright (c) 2000 The OpenSSL Project.  All rights reserved.
     7  *
     8  * Redistribution and use in source and binary forms, with or without
     9  * modification, are permitted provided that the following conditions
    10  * are met:
    11  *
    12  * 1. Redistributions of source code must retain the above copyright
    13  *    notice, this list of conditions and the following disclaimer. 
    14  *
    15  * 2. Redistributions in binary form must reproduce the above copyright
    16  *    notice, this list of conditions and the following disclaimer in
    17  *    the documentation and/or other materials provided with the
    18  *    distribution.
    19  *
    20  * 3. All advertising materials mentioning features or use of this
    21  *    software must display the following acknowledgment:
    22  *    "This product includes software developed by the OpenSSL Project
    23  *    for use in the OpenSSL Toolkit. (http://www.OpenSSL.org/)"
    24  *
    25  * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
    26  *    endorse or promote products derived from this software without
    27  *    prior written permission. For written permission, please contact
    28  *    licensing@OpenSSL.org.
    29  *
    30  * 5. Products derived from this software may not be called "OpenSSL"
    31  *    nor may "OpenSSL" appear in their names without prior written
    32  *    permission of the OpenSSL Project.
    33  *
    34  * 6. Redistributions of any form whatsoever must retain the following
    35  *    acknowledgment:
    36  *    "This product includes software developed by the OpenSSL Project
    37  *    for use in the OpenSSL Toolkit (http://www.OpenSSL.org/)"
    38  *
    39  * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
    40  * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
    41  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
    42  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
    43  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    44  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
    45  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
    46  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
    47  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
    48  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
    49  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
    50  * OF THE POSSIBILITY OF SUCH DAMAGE.
    51  * ====================================================================
    52  *
    53  * This product includes cryptographic software written by Eric Young
    54  * (eay@cryptsoft.com).  This product includes software written by Tim
    55  * Hudson (tjh@cryptsoft.com).
    56  *
    57  */
    58  /*
    59  © Portions copyright (c) 2006 Nokia Corporation.  All rights reserved.
    60  */
    61 
    62 #ifndef HEADER_DSO_H
    63 #define HEADER_DSO_H
    64 
    65 #if (defined(__SYMBIAN32__) && !defined(SYMBIAN))
    66 #define SYMBIAN
    67 #endif
    68 
    69 #ifdef SYMBIAN
    70 #include <e32def.h>
    71 #endif
    72 #include <openssl/crypto.h>
    73 
    74 #ifdef __cplusplus
    75 extern "C" {
    76 #endif
    77 
    78 /* These values are used as commands to DSO_ctrl() */
    79 #define DSO_CTRL_GET_FLAGS	1
    80 #define DSO_CTRL_SET_FLAGS	2
    81 #define DSO_CTRL_OR_FLAGS	3
    82 
    83 /* By default, DSO_load() will translate the provided filename into a form
    84  * typical for the platform (more specifically the DSO_METHOD) using the
    85  * dso_name_converter function of the method. Eg. win32 will transform "blah"
    86  * into "blah.dll", and dlfcn will transform it into "libblah.so". The
    87  * behaviour can be overriden by setting the name_converter callback in the DSO
    88  * object (using DSO_set_name_converter()). This callback could even utilise
    89  * the DSO_METHOD's converter too if it only wants to override behaviour for
    90  * one or two possible DSO methods. However, the following flag can be set in a
    91  * DSO to prevent *any* native name-translation at all - eg. if the caller has
    92  * prompted the user for a path to a driver library so the filename should be
    93  * interpreted as-is. */
    94 #define DSO_FLAG_NO_NAME_TRANSLATION		0x01
    95 /* An extra flag to give if only the extension should be added as
    96  * translation.  This is obviously only of importance on Unix and
    97  * other operating systems where the translation also may prefix
    98  * the name with something, like 'lib', and ignored everywhere else.
    99  * This flag is also ignored if DSO_FLAG_NO_NAME_TRANSLATION is used
   100  * at the same time. */
   101 #define DSO_FLAG_NAME_TRANSLATION_EXT_ONLY	0x02
   102 
   103 /* The following flag controls the translation of symbol names to upper
   104  * case.  This is currently only being implemented for OpenVMS.
   105  */
   106 #define DSO_FLAG_UPCASE_SYMBOL			0x10
   107 
   108 /* This flag loads the library with public symbols.
   109  * Meaning: The exported symbols of this library are public
   110  * to all libraries loaded after this library.
   111  * At the moment only implemented in unix.
   112  */
   113 #define DSO_FLAG_GLOBAL_SYMBOLS			0x20
   114 
   115 
   116 typedef void (*DSO_FUNC_TYPE)(void);
   117 
   118 typedef struct dso_st DSO;
   119 
   120 /* The function prototype used for method functions (or caller-provided
   121  * callbacks) that transform filenames. They are passed a DSO structure pointer
   122  * (or NULL if they are to be used independantly of a DSO object) and a
   123  * filename to transform. They should either return NULL (if there is an error
   124  * condition) or a newly allocated string containing the transformed form that
   125  * the caller will need to free with OPENSSL_free() when done. */
   126 typedef char* (*DSO_NAME_CONVERTER_FUNC)(DSO *, const char *);
   127 /* The function prototype used for method functions (or caller-provided
   128  * callbacks) that merge two file specifications. They are passed a
   129  * DSO structure pointer (or NULL if they are to be used independantly of
   130  * a DSO object) and two file specifications to merge. They should
   131  * either return NULL (if there is an error condition) or a newly allocated
   132  * string containing the result of merging that the caller will need
   133  * to free with OPENSSL_free() when done.
   134  * Here, merging means that bits and pieces are taken from each of the
   135  * file specifications and added together in whatever fashion that is
   136  * sensible for the DSO method in question.  The only rule that really
   137  * applies is that if the two specification contain pieces of the same
   138  * type, the copy from the first string takes priority.  One could see
   139  * it as the first specification is the one given by the user and the
   140  * second being a bunch of defaults to add on if they're missing in the
   141  * first. */
   142 typedef char* (*DSO_MERGER_FUNC)(DSO *, const char *, const char *);
   143 
   144 typedef struct dso_meth_st
   145 	{
   146 	const char *name;
   147 	/* Loads a shared library, NB: new DSO_METHODs must ensure that a
   148 	 * successful load populates the loaded_filename field, and likewise a
   149 	 * successful unload OPENSSL_frees and NULLs it out. */
   150 	int (*dso_load)(DSO *dso);
   151 	/* Unloads a shared library */
   152 	int (*dso_unload)(DSO *dso);
   153 	/* Binds a variable */
   154 	void *(*dso_bind_var)(DSO *dso, const char *symname);
   155 	/* Binds a function - assumes a return type of DSO_FUNC_TYPE.
   156 	 * This should be cast to the real function prototype by the
   157 	 * caller. Platforms that don't have compatible representations
   158 	 * for different prototypes (this is possible within ANSI C)
   159 	 * are highly unlikely to have shared libraries at all, let
   160 	 * alone a DSO_METHOD implemented for them. */
   161 	DSO_FUNC_TYPE (*dso_bind_func)(DSO *dso, const char *symname);
   162 
   163 /* I don't think this would actually be used in any circumstances. */
   164 #if 0
   165 	/* Unbinds a variable */
   166 	int (*dso_unbind_var)(DSO *dso, char *symname, void *symptr);
   167 	/* Unbinds a function */
   168 	int (*dso_unbind_func)(DSO *dso, char *symname, DSO_FUNC_TYPE symptr);
   169 #endif
   170 	/* The generic (yuck) "ctrl()" function. NB: Negative return
   171 	 * values (rather than zero) indicate errors. */
   172 	long (*dso_ctrl)(DSO *dso, int cmd, long larg, void *parg);
   173 	/* The default DSO_METHOD-specific function for converting filenames to
   174 	 * a canonical native form. */
   175 	DSO_NAME_CONVERTER_FUNC dso_name_converter;
   176 	/* The default DSO_METHOD-specific function for converting filenames to
   177 	 * a canonical native form. */
   178 	DSO_MERGER_FUNC dso_merger;
   179 
   180 	/* [De]Initialisation handlers. */
   181 	int (*init)(DSO *dso);
   182 	int (*finish)(DSO *dso);
   183 	} DSO_METHOD;
   184 
   185 /**********************************************************************/
   186 /* The low-level handle type used to refer to a loaded shared library */
   187 
   188 struct dso_st
   189 	{
   190 	DSO_METHOD *meth;
   191 	/* Standard dlopen uses a (void *). Win32 uses a HANDLE. VMS
   192 	 * doesn't use anything but will need to cache the filename
   193 	 * for use in the dso_bind handler. All in all, let each
   194 	 * method control its own destiny. "Handles" and such go in
   195 	 * a STACK. */
   196 	STACK *meth_data;
   197 	int references;
   198 	int flags;
   199 	/* For use by applications etc ... use this for your bits'n'pieces,
   200 	 * don't touch meth_data! */
   201 	CRYPTO_EX_DATA ex_data;
   202 	/* If this callback function pointer is set to non-NULL, then it will
   203 	 * be used in DSO_load() in place of meth->dso_name_converter. NB: This
   204 	 * should normally set using DSO_set_name_converter(). */
   205 	DSO_NAME_CONVERTER_FUNC name_converter;
   206 	/* If this callback function pointer is set to non-NULL, then it will
   207 	 * be used in DSO_load() in place of meth->dso_merger. NB: This
   208 	 * should normally set using DSO_set_merger(). */
   209 	DSO_MERGER_FUNC merger;
   210 	/* This is populated with (a copy of) the platform-independant
   211 	 * filename used for this DSO. */
   212 	char *filename;
   213 	/* This is populated with (a copy of) the translated filename by which
   214 	 * the DSO was actually loaded. It is NULL iff the DSO is not currently
   215 	 * loaded. NB: This is here because the filename translation process
   216 	 * may involve a callback being invoked more than once not only to
   217 	 * convert to a platform-specific form, but also to try different
   218 	 * filenames in the process of trying to perform a load. As such, this
   219 	 * variable can be used to indicate (a) whether this DSO structure
   220 	 * corresponds to a loaded library or not, and (b) the filename with
   221 	 * which it was actually loaded. */
   222 	char *loaded_filename;
   223 	};
   224 
   225 
   226 IMPORT_C DSO *	DSO_new(void);
   227 IMPORT_C DSO *	DSO_new_method(DSO_METHOD *method);
   228 IMPORT_C int	DSO_free(DSO *dso);
   229 IMPORT_C int	DSO_flags(DSO *dso);
   230 IMPORT_C int	DSO_up_ref(DSO *dso);
   231 IMPORT_C long	DSO_ctrl(DSO *dso, int cmd, long larg, void *parg);
   232 
   233 /* This function sets the DSO's name_converter callback. If it is non-NULL,
   234  * then it will be used instead of the associated DSO_METHOD's function. If
   235  * oldcb is non-NULL then it is set to the function pointer value being
   236  * replaced. Return value is non-zero for success. */
   237 IMPORT_C int	DSO_set_name_converter(DSO *dso, DSO_NAME_CONVERTER_FUNC cb,
   238 				DSO_NAME_CONVERTER_FUNC *oldcb);
   239 /* These functions can be used to get/set the platform-independant filename
   240  * used for a DSO. NB: set will fail if the DSO is already loaded. */
   241 IMPORT_C const char *DSO_get_filename(DSO *dso);
   242 IMPORT_C int	DSO_set_filename(DSO *dso, const char *filename);
   243 /* This function will invoke the DSO's name_converter callback to translate a
   244  * filename, or if the callback isn't set it will instead use the DSO_METHOD's
   245  * converter. If "filename" is NULL, the "filename" in the DSO itself will be
   246  * used. If the DSO_FLAG_NO_NAME_TRANSLATION flag is set, then the filename is
   247  * simply duplicated. NB: This function is usually called from within a
   248  * DSO_METHOD during the processing of a DSO_load() call, and is exposed so that
   249  * caller-created DSO_METHODs can do the same thing. A non-NULL return value
   250  * will need to be OPENSSL_free()'d. */
   251 IMPORT_C char	*DSO_convert_filename(DSO *dso, const char *filename);
   252 /* This function will invoke the DSO's merger callback to merge two file
   253  * specifications, or if the callback isn't set it will instead use the
   254  * DSO_METHOD's merger.  A non-NULL return value will need to be
   255  * OPENSSL_free()'d. */
   256 IMPORT_C char	*DSO_merge(DSO *dso, const char *filespec1, const char *filespec2);
   257 /* If the DSO is currently loaded, this returns the filename that it was loaded
   258  * under, otherwise it returns NULL. So it is also useful as a test as to
   259  * whether the DSO is currently loaded. NB: This will not necessarily return
   260  * the same value as DSO_convert_filename(dso, dso->filename), because the
   261  * DSO_METHOD's load function may have tried a variety of filenames (with
   262  * and/or without the aid of the converters) before settling on the one it
   263  * actually loaded. */
   264 IMPORT_C const char *DSO_get_loaded_filename(DSO *dso);
   265 
   266 IMPORT_C void	DSO_set_default_method(DSO_METHOD *meth);
   267 IMPORT_C DSO_METHOD *DSO_get_default_method(void);
   268 IMPORT_C DSO_METHOD *DSO_get_method(DSO *dso);
   269 IMPORT_C DSO_METHOD *DSO_set_method(DSO *dso, DSO_METHOD *meth);
   270 
   271 /* The all-singing all-dancing load function, you normally pass NULL
   272  * for the first and third parameters. Use DSO_up and DSO_free for
   273  * subsequent reference count handling. Any flags passed in will be set
   274  * in the constructed DSO after its init() function but before the
   275  * load operation. If 'dso' is non-NULL, 'flags' is ignored. */
   276 IMPORT_C DSO *DSO_load(DSO *dso, const char *filename, DSO_METHOD *meth, int flags);
   277 
   278 /* This function binds to a variable inside a shared library. */
   279 IMPORT_C void *DSO_bind_var(DSO *dso, const char *symname);
   280 
   281 /* This function binds to a function inside a shared library. */
   282 IMPORT_C DSO_FUNC_TYPE DSO_bind_func(DSO *dso, const char *symname);
   283 
   284 /* This method is the default, but will beg, borrow, or steal whatever
   285  * method should be the default on any particular platform (including
   286  * DSO_METH_null() if necessary). */
   287 IMPORT_C DSO_METHOD *DSO_METHOD_openssl(void);
   288 
   289 /* This method is defined for all platforms - if a platform has no
   290  * DSO support then this will be the only method! */
   291 IMPORT_C DSO_METHOD *DSO_METHOD_null(void);
   292 
   293 /* If DSO_DLFCN is defined, the standard dlfcn.h-style functions
   294  * (dlopen, dlclose, dlsym, etc) will be used and incorporated into
   295  * this method. If not, this method will return NULL. */
   296 IMPORT_C DSO_METHOD *DSO_METHOD_dlfcn(void);
   297 
   298 /* If DSO_DL is defined, the standard dl.h-style functions (shl_load, 
   299  * shl_unload, shl_findsym, etc) will be used and incorporated into
   300  * this method. If not, this method will return NULL. */
   301 IMPORT_C DSO_METHOD *DSO_METHOD_dl(void);
   302 
   303 
   304 /* BEGIN ERROR CODES */
   305 /* The following lines are auto generated by the script mkerr.pl. Any changes
   306  * made after this point may be overwritten when the script is next run.
   307  */
   308 IMPORT_C void ERR_load_DSO_strings(void);
   309 
   310 /* Error codes for the DSO functions. */
   311 
   312 /* Function codes. */
   313 #define DSO_F_DLFCN_BIND_FUNC				 100
   314 #define DSO_F_DLFCN_BIND_VAR				 101
   315 #define DSO_F_DLFCN_LOAD				 102
   316 #define DSO_F_DLFCN_MERGER				 130
   317 #define DSO_F_DLFCN_NAME_CONVERTER			 123
   318 #define DSO_F_DLFCN_UNLOAD				 103
   319 #define DSO_F_DL_BIND_FUNC				 104
   320 #define DSO_F_DL_BIND_VAR				 105
   321 #define DSO_F_DL_LOAD					 106
   322 #define DSO_F_DL_MERGER					 131
   323 #define DSO_F_DL_NAME_CONVERTER				 124
   324 #define DSO_F_DL_UNLOAD					 107
   325 #define DSO_F_DSO_BIND_FUNC				 108
   326 #define DSO_F_DSO_BIND_VAR				 109
   327 #define DSO_F_DSO_CONVERT_FILENAME			 126
   328 #define DSO_F_DSO_CTRL					 110
   329 #define DSO_F_DSO_FREE					 111
   330 #define DSO_F_DSO_GET_FILENAME				 127
   331 #define DSO_F_DSO_GET_LOADED_FILENAME			 128
   332 #define DSO_F_DSO_LOAD					 112
   333 #define DSO_F_DSO_MERGE					 132
   334 #define DSO_F_DSO_NEW_METHOD				 113
   335 #define DSO_F_DSO_SET_FILENAME				 129
   336 #define DSO_F_DSO_SET_NAME_CONVERTER			 122
   337 #define DSO_F_DSO_UP_REF				 114
   338 #define DSO_F_VMS_BIND_SYM				 115
   339 #define DSO_F_VMS_LOAD					 116
   340 #define DSO_F_VMS_MERGER				 133
   341 #define DSO_F_VMS_UNLOAD				 117
   342 #define DSO_F_WIN32_BIND_FUNC				 118
   343 #define DSO_F_WIN32_BIND_VAR				 119
   344 #define DSO_F_WIN32_JOINER				 135
   345 #define DSO_F_WIN32_LOAD				 120
   346 #define DSO_F_WIN32_MERGER				 134
   347 #define DSO_F_WIN32_NAME_CONVERTER			 125
   348 #define DSO_F_WIN32_SPLITTER				 136
   349 #define DSO_F_WIN32_UNLOAD				 121
   350 
   351 /* Reason codes. */
   352 #define DSO_R_CTRL_FAILED				 100
   353 #define DSO_R_DSO_ALREADY_LOADED			 110
   354 #define DSO_R_EMPTY_FILE_STRUCTURE			 113
   355 #define DSO_R_FAILURE					 114
   356 #define DSO_R_FILENAME_TOO_BIG				 101
   357 #define DSO_R_FINISH_FAILED				 102
   358 #define DSO_R_INCORRECT_FILE_SYNTAX			 115
   359 #define DSO_R_LOAD_FAILED				 103
   360 #define DSO_R_NAME_TRANSLATION_FAILED			 109
   361 #define DSO_R_NO_FILENAME				 111
   362 #define DSO_R_NO_FILE_SPECIFICATION			 116
   363 #define DSO_R_NULL_HANDLE				 104
   364 #define DSO_R_SET_FILENAME_FAILED			 112
   365 #define DSO_R_STACK_ERROR				 105
   366 #define DSO_R_SYM_FAILURE				 106
   367 #define DSO_R_UNLOAD_FAILED				 107
   368 #define DSO_R_UNSUPPORTED				 108
   369 
   370 #ifdef  __cplusplus
   371 }
   372 #endif
   373 #endif