1 // Copyright 1995-2016 The OpenSSL Project Authors. All Rights Reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef OPENSSL_HEADER_EX_DATA_H 16 #define OPENSSL_HEADER_EX_DATA_H 17 18 #include <openssl/base.h> // IWYU pragma: export 19 20 #if defined(__cplusplus) 21 extern "C" { 22 #endif 23 24 25 // ex_data is a mechanism for associating arbitrary extra data with objects. 26 // For each type of object that supports ex_data, different users can be 27 // assigned indexes in which to store their data. Each index has callback 28 // functions that are called when an object of that type is freed or 29 // duplicated. 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_DATA, in the public API, is an opaque struct that is never returned 75 // from the library. 76 typedef struct crypto_ex_data_st CRYPTO_EX_DATA; 77 78 // CRYPTO_EX_free is a callback function that is called when an object of the 79 // class with extra data pointers is being destroyed. For example, if this 80 // callback has been passed to |SSL_get_ex_new_index| then it may be called each 81 // time an |SSL*| is destroyed. 82 // 83 // |parent| and |ad| will be NULL. Historically, the parent object was passed in 84 // |parent|, but accessing the pointer was not safe because |parent| was in the 85 // process of being destroyed. If the callback has access to some other pointer 86 // to the parent object, it must not pass the pointer to any BoringSSL APIs. 87 // Mid-destruction, invariants on the parent object no longer hold. 88 // 89 // The arguments |argl| and |argp| contain opaque values that were given to 90 // |CRYPTO_get_ex_new_index_ex|. 91 // 92 // This callback may be called with a NULL value for |ptr| if the object has no 93 // value set for this index. However, the callbacks may also be skipped entirely 94 // if no extra data pointers are set on the object at all. 95 typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad, 96 int index, long argl, void *argp); 97 98 99 // Deprecated functions. 100 101 // CRYPTO_cleanup_all_ex_data does nothing. 102 OPENSSL_EXPORT void CRYPTO_cleanup_all_ex_data(void); 103 104 // CRYPTO_EX_dup is a legacy callback function type which is ignored. 105 typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from, 106 void **from_d, int index, long argl, void *argp); 107 108 // CRYPTO_EX_unused is a placeholder for an unused callback. It is aliased to 109 // int to ensure non-NULL callers fail to compile rather than fail silently. 110 typedef int CRYPTO_EX_unused; 111 112 113 #if defined(__cplusplus) 114 } // extern C 115 #endif 116 117 #endif // OPENSSL_HEADER_EX_DATA_H 118