ex_data.h

All headers

ex_data is a mechanism for associating arbitrary extra data with objects. 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 an object of that type is freed or duplicated.

  1. Type-specific functions
  2. TYPE_get_ex_new_index
  3. TYPE_set_ex_data
  4. TYPE_get_ex_data
  5. TYPE_set_app_data
  6. TYPE_get_app_data
  7. Callback types
  8. Deprecated functions
  9. CRYPTO_cleanup_all_ex_data
typedef struct crypto_ex_data_st CRYPTO_EX_DATA;

Type-specific functions.

#if 0  // Sample

Each type that supports ex_data provides three functions:

TYPE_get_ex_new_index allocates a new index for TYPE. An optional free_func argument may be provided which is called when the owning object is destroyed. See CRYPTO_EX_free for details. The argl and argp arguments are opaque values that are passed to the callback. It returns the new index or a negative number on error.

OPENSSL_EXPORT int TYPE_get_ex_new_index(long argl, void *argp,
                                         CRYPTO_EX_unused *unused,
                                         CRYPTO_EX_dup *dup_unused,
                                         CRYPTO_EX_free *free_func);

TYPE_set_ex_data sets an extra data pointer on t. The index argument must 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);

Some types additionally preallocate index zero, with all callbacks set to NULL. Applications that do not need the general ex_data machinery may use this instead.

TYPE_set_app_data sets t's application data pointer to arg. It returns one on success and zero on error.

OPENSSL_EXPORT int TYPE_set_app_data(TYPE *t, void *arg);

TYPE_get_app_data returns the application data pointer for t, or NULL if no such pointer exists.

OPENSSL_EXPORT void *TYPE_get_app_data(const TYPE *t);
#endif  // Sample

Callback types.

CRYPTO_EX_free is a callback function that is called when an object of the class with extra data pointers is being destroyed. For example, if this callback has been passed to SSL_get_ex_new_index then it may be called each time an SSL* is destroyed.

The callback is passed the to-be-destroyed object (i.e. the SSL*) in parent. As parent will shortly be destroyed, callers must not perform operations that would increment its reference count, pass ownership, or assume the object outlives the function call. The arguments argl and argp contain opaque values that were given to CRYPTO_get_ex_new_index_ex.

This callback may be called with a NULL value for ptr if parent has no value set for this index. However, the callbacks may also be skipped entirely if no extra data pointers are set on parent at all.

typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
                            int index, long argl, void *argp);

Deprecated functions.

CRYPTO_cleanup_all_ex_data does nothing.

OPENSSL_EXPORT void CRYPTO_cleanup_all_ex_data(void);

CRYPTO_EX_dup is a legacy callback function type which is ignored.

typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
                          void **from_d, int index, long argl, void *argp);