1 /* 2 * Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved. 3 * 4 * Licensed under the OpenSSL license (the "License"). You may not use 5 * this file except in compliance with the License. You can obtain a copy 6 * in the file LICENSE in the source distribution or at 7 * https://www.openssl.org/source/license.html 8 */ 9 10 #ifndef OPENSSL_HEADER_EX_DATA_H 11 #define OPENSSL_HEADER_EX_DATA_H 12 13 #include <openssl/base.h> 14 15 #include <openssl/stack.h> 16 17 #if defined(__cplusplus) 18 extern "C" { 19 #endif 20 21 22 // ex_data is a mechanism for associating arbitrary extra data with objects. 23 // For each type of object that supports ex_data, different users can be 24 // assigned indexes in which to store their data. Each index has callback 25 // functions that are called when an object of that type is freed or 26 // duplicated. 27 28 29 typedef struct crypto_ex_data_st CRYPTO_EX_DATA; 30 31 32 // Type-specific functions. 33 34 #if 0 // Sample 35 36 // Each type that supports ex_data provides three functions: 37 38 // TYPE_get_ex_new_index allocates a new index for |TYPE|. An optional 39 // |free_func| argument may be provided which is called when the owning object 40 // is destroyed. See |CRYPTO_EX_free| for details. The |argl| and |argp| 41 // arguments are opaque values that are passed to the callback. It returns the 42 // new index or a negative number on error. 43 OPENSSL_EXPORT int TYPE_get_ex_new_index(long argl, void *argp, 44 CRYPTO_EX_unused *unused, 45 CRYPTO_EX_dup *dup_unused, 46 CRYPTO_EX_free *free_func); 47 48 // TYPE_set_ex_data sets an extra data pointer on |t|. The |index| argument 49 // must have been returned from a previous call to |TYPE_get_ex_new_index|. 50 OPENSSL_EXPORT int TYPE_set_ex_data(TYPE *t, int index, void *arg); 51 52 // TYPE_get_ex_data returns an extra data pointer for |t|, or NULL if no such 53 // pointer exists. The |index| argument should have been returned from a 54 // previous call to |TYPE_get_ex_new_index|. 55 OPENSSL_EXPORT void *TYPE_get_ex_data(const TYPE *t, int index); 56 57 // Some types additionally preallocate index zero, with all callbacks set to 58 // NULL. Applications that do not need the general ex_data machinery may use 59 // this instead. 60 61 // TYPE_set_app_data sets |t|'s application data pointer to |arg|. It returns 62 // one on success and zero on error. 63 OPENSSL_EXPORT int TYPE_set_app_data(TYPE *t, void *arg); 64 65 // TYPE_get_app_data returns the application data pointer for |t|, or NULL if no 66 // such pointer exists. 67 OPENSSL_EXPORT void *TYPE_get_app_data(const TYPE *t); 68 69 #endif // Sample 70 71 72 // Callback types. 73 74 // CRYPTO_EX_free is a callback function that is called when an object of the 75 // class with extra data pointers is being destroyed. For example, if this 76 // callback has been passed to |SSL_get_ex_new_index| then it may be called each 77 // time an |SSL*| is destroyed. 78 // 79 // The callback is passed the to-be-destroyed object (i.e. the |SSL*|) in 80 // |parent|. As |parent| will shortly be destroyed, callers must not perform 81 // operations that would increment its reference count, pass ownership, or 82 // assume the object outlives the function call. The arguments |argl| and |argp| 83 // contain opaque values that were given to |CRYPTO_get_ex_new_index_ex|. 84 // 85 // This callback may be called with a NULL value for |ptr| if |parent| has no 86 // value set for this index. However, the callbacks may also be skipped entirely 87 // if no extra data pointers are set on |parent| at all. 88 typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, 89 int index, long argl, void *argp); 90 91 92 // Deprecated functions. 93 94 // CRYPTO_cleanup_all_ex_data does nothing. 95 OPENSSL_EXPORT void CRYPTO_cleanup_all_ex_data(void); 96 97 // CRYPTO_EX_dup is a legacy callback function type which is ignored. 98 typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from, 99 void **from_d, int index, long argl, void *argp); 100 101 102 // Private structures. 103 104 // CRYPTO_EX_unused is a placeholder for an unused callback. It is aliased to 105 // int to ensure non-NULL callers fail to compile rather than fail silently. 106 typedef int CRYPTO_EX_unused; 107 108 struct crypto_ex_data_st { 109 STACK_OF(void) *sk; 110 }; 111 112 113 #if defined(__cplusplus) 114 } // extern C 115 #endif 116 117 #endif // OPENSSL_HEADER_EX_DATA_H 118