diff options
Diffstat (limited to 'src/include/openssl/ex_data.h')
| -rw-r--r-- | src/include/openssl/ex_data.h | 168 |
1 files changed, 41 insertions, 127 deletions
diff --git a/src/include/openssl/ex_data.h b/src/include/openssl/ex_data.h index f61501a..2303eb4 100644 --- a/src/include/openssl/ex_data.h +++ b/src/include/openssl/ex_data.h @@ -119,21 +119,51 @@ extern "C" { /* ex_data is a mechanism for associating arbitrary extra data with objects. - * The different types of objects which can have data associated with them are - * called "classes" and there are predefined classes for all the OpenSSL - * objects that support ex_data. - * - * Within a given class, different users can be assigned indexes in which to - * store their data. Each index has callback functions that are called when a - * new object of that type is created, freed and duplicated. */ + * For each type of object that supports ex_data, different users can be + * assigned indexes in which to store their data. Each index has callback + * functions that are called when a new object of that type is created, freed + * and duplicated. */ typedef struct crypto_ex_data_st CRYPTO_EX_DATA; + +/* Type-specific functions. + * + * Each type that supports ex_data provides three functions: */ + +#if 0 /* Sample */ + +/* |TYPE_get_ex_new_index| allocates a new index for |TYPE|. See the + * descriptions of the callback typedefs for details of when they are + * called. Any of the callback arguments may be NULL. The |argl| and |argp| + * arguments are opaque values that are passed to the callbacks. It returns the + * new index or a negative number on error. + * + * TODO(fork): this should follow the standard calling convention. */ +OPENSSL_EXPORT int TYPE_get_ex_new_index(long argl, void *argp, + CRYPTO_EX_new *new_func, + CRYPTO_EX_dup *dup_func, + CRYPTO_EX_free *free_func); + +/* |TYPE_set_ex_data| sets an extra data pointer on |t|. The |index| argument + * should have been returned from a previous call to |TYPE_get_ex_new_index|. */ +OPENSSL_EXPORT int TYPE_set_ex_data(TYPE *t, int index, void *arg); + +/* |TYPE_get_ex_data| returns an extra data pointer for |t|, or NULL if no such + * pointer exists. The |index| argument should have been returned from a + * previous call to |TYPE_get_ex_new_index|. */ +OPENSSL_EXPORT void *TYPE_get_ex_data(const TYPE *t, int index); + +#endif /* Sample */ + + +/* Callback types. */ + /* CRYPTO_EX_new is the type of a callback function that is called whenever a * new object of a given class is created. For example, if this callback has - * been passed to |CRYPTO_get_ex_new_index| with a |class| of - * |CRYPTO_EX_INDEX_SSL| then it'll be called each time an SSL* is created. + * been passed to |SSL_get_ex_new_index| then it'll be called each time an SSL* + * is created. * * The callback is passed the new object (i.e. the SSL*) in |parent|. The * arguments |argl| and |argp| contain opaque values that were given to @@ -166,126 +196,10 @@ typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from, void **from_d, int index, long argl, void *argp); -/* CRYPTO_get_ex_new_index allocates a new index for ex_data linked with - * objects of the given |class|. This should not be called directly, rather - * each class of object should provide a wrapper function that sets - * |class_value| correctly. - * - * The |class_value| argument should be one of |CRYPTO_EX_INDEX_*| or a - * user-defined class value returned from |CRYPTO_ex_data_new_class|. - * - * See the descriptions of the callback typedefs for details of when they are - * called. Any of the callback arguments may be NULL. The |argl| and |argp| - * arguments are opaque values that are passed to the callbacks. - * - * It returns the new index, or a negative number on error. - * - * TODO(fork): this should follow the standard calling convention. - * - * TODO(fork): replace the class_value with a pointer to EX_CLASS_ITEM. Saves - * having that hash table and some of the lock-bouncing. Maybe have every - * module have a private global EX_CLASS_ITEM somewhere and any direct callers - * of CRYPTO_{get,set}_ex_data{,_index} would have to always call the - * wrappers. */ -OPENSSL_EXPORT int CRYPTO_get_ex_new_index(int class_value, long argl, - void *argp, CRYPTO_EX_new *new_func, - CRYPTO_EX_dup *dup_func, - CRYPTO_EX_free *free_func); - -/* CRYPTO_set_ex_data sets an extra data pointer on a given object. This should - * not be called directly, rather each class of object should provide a wrapper - * function. - * - * The |index| argument should have been returned from a previous call to - * |CRYPTO_get_ex_new_index|. */ -OPENSSL_EXPORT int CRYPTO_set_ex_data(CRYPTO_EX_DATA *ad, int index, void *val); - -/* CRYPTO_set_ex_data return an extra data pointer for a given object, or NULL - * if no such index exists. This should not be called directly, rather each - * class of object should provide a wrapper function. - * - * The |index| argument should have been returned from a previous call to - * |CRYPTO_get_ex_new_index|. */ -OPENSSL_EXPORT void *CRYPTO_get_ex_data(const CRYPTO_EX_DATA *ad, int index); - -/* CRYPTO_EX_INDEX_* are the built-in classes of objects. - * - * User defined classes start at 100. - * - * TODO(fork): WARNING: these are called "INDEX", but they aren't! */ -#define CRYPTO_EX_INDEX_BIO 0 -#define CRYPTO_EX_INDEX_SSL 1 -#define CRYPTO_EX_INDEX_SSL_CTX 2 -#define CRYPTO_EX_INDEX_SSL_SESSION 3 -#define CRYPTO_EX_INDEX_X509_STORE 4 -#define CRYPTO_EX_INDEX_X509_STORE_CTX 5 -#define CRYPTO_EX_INDEX_RSA 6 -#define CRYPTO_EX_INDEX_DSA 7 -#define CRYPTO_EX_INDEX_DH 8 -#define CRYPTO_EX_INDEX_ENGINE 9 -#define CRYPTO_EX_INDEX_X509 10 -#define CRYPTO_EX_INDEX_UI 11 -#define CRYPTO_EX_INDEX_EC_KEY 12 -#define CRYPTO_EX_INDEX_EC_GROUP 13 -#define CRYPTO_EX_INDEX_COMP 14 -#define CRYPTO_EX_INDEX_STORE 15 - - -/* User-defined classes of objects. - * - * Core OpenSSL code has predefined class values given above (the - * |CRYPTO_EX_INDEX_*| values). It's possible to get dynamic class values - * assigned for user-defined objects. */ - -/* CRYPTO_ex_data_new_class returns a fresh class value for a user-defined type - * that wishes to use ex_data. - * - * TODO(fork): hopefully remove this. */ -OPENSSL_EXPORT int CRYPTO_ex_data_new_class(void); - - -/* Embedding, allocating and freeing |CRYPTO_EX_DATA| structures for objects - * that embed them. */ - -/* CRYPTO_new_ex_data initialises a newly allocated |CRYPTO_EX_DATA| which is - * embedded inside of |obj| which is of class |class_value|. Returns one on - * success and zero otherwise. */ -OPENSSL_EXPORT int CRYPTO_new_ex_data(int class_value, void *obj, - CRYPTO_EX_DATA *ad); - -/* CRYPTO_dup_ex_data duplicates |from| into a freshly allocated - * |CRYPTO_EX_DATA|, |to|. Both of which are inside objects of the given - * class. It returns one on success and zero otherwise. */ -OPENSSL_EXPORT int CRYPTO_dup_ex_data(int class_value, CRYPTO_EX_DATA *to, - const CRYPTO_EX_DATA *from); - -/* CRYPTO_free_ex_data frees |ad|, which is embedded inside |obj|, which is an - * object of the given class. */ -OPENSSL_EXPORT void CRYPTO_free_ex_data(int class_value, void *obj, - CRYPTO_EX_DATA *ad); - - -/* Handling different ex_data implementations. */ - -/* CRYPTO_EX_DATA_IMPL is the opaque type of an implementation of ex_data. */ -typedef struct st_CRYPTO_EX_DATA_IMPL CRYPTO_EX_DATA_IMPL; - -/* CRYPTO_get_ex_data_implementation returns the current implementation of - * ex_data. */ -OPENSSL_EXPORT const CRYPTO_EX_DATA_IMPL *CRYPTO_get_ex_data_implementation( - void); - -/* CRYPTO_set_ex_data_implementation sets the implementation of ex_data to use, - * unless ex_data has already been used and the default implementation - * installed. It returns one on success and zero otherwise. */ -OPENSSL_EXPORT int CRYPTO_set_ex_data_implementation( - const CRYPTO_EX_DATA_IMPL *impl); - -/* Private functions. */ +/* Deprecated functions. */ -/* CRYPTO_cleanup_all_ex_data cleans up all ex_data state. It assumes that no - * other threads are executing code that might call ex_data functions. */ +/* CRYPTO_cleanup_all_ex_data does nothing. */ OPENSSL_EXPORT void CRYPTO_cleanup_all_ex_data(void); struct crypto_ex_data_st { |