Fri Aug 17 00:17:43 2018

Asterisk developer's documentation


optional_api.h File Reference

Optional API function macros. More...

Go to the source code of this file.

Defines

#define __stringify(x)   __stringify_1(x)
#define __stringify_1(x)   #x
#define AST_OPTIONAL_API(result, name, proto, stub)
#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)
#define AST_OPTIONAL_API_NAME(name)   __##name
#define AST_OPTIONAL_API_UNAVAILABLE   INT_MIN
 A common value for optional API stub functions to return.

Detailed Description

Optional API function macros.

Some Asterisk API functions are provided by loadable modules, thus, they may or may not be available at run time depending on whether the providing module has been loaded or not. In addition, there are some modules that are consumers of these APIs that *optionally* use them; they have only a part of their functionality dependent on the APIs, and can provide the remainder even if the APIs are not available.

To accomodate this situation, the AST_OPTIONAL_API macro allows an API function to be declared in a special way, if Asterisk being built on a platform that supports special compiler and dynamic linker attributes. If so the API function will actually be a weak symbol, which means if the provider of the API is not loaded, the symbol can still be referenced (unlike a strong symbol, which would cause an immediate fault if not defined when referenced), but it will return NULL signifying the linker/loader was not able to resolve the symbol. In addition, the macro defines a hidden 'stub' version of the API call, using a provided function body, and uses various methods to make the API function symbol actually resolve to that hidden stub, but only when the *real* provider of the symbol has not been found.

An example can be found in agi.h:

 AST_OPTIONAL_API(int, ast_agi_register, (struct ast_module *mod, agi_command *cmd),
                  { return AST_OPTIONAL_API_UNAVAILABLE; });

This defines the 'ast_agi_register' function as an optional API; if a consumer of this API is loaded when there is no provider of it, then calling this function will actually call the hidden stub, and return the value AST_OPTIONAL_API_UNAVAILABLE. This allows the consumer to safely know that the API is not available, and to avoid using any other APIs from the not-present provider.

In addition to this declaration in the header file, the actual definition of the API function must use the AST_OPTIONAL_API_NAME macro to (possibly) modify the real name of the API function, depending on the specific implementation requirements. The corresponding example from res_agi.c:

 int AST_OPTIONAL_API_NAME(ast_agi_register)(struct ast_module *mod, agi_command *cmd)
 {
 ...
 }

In the module providing the API, the AST_OPTIONAL_API macro must be informed that it should not build the hidden stub function or apply special aliases to the function prototype; this can be done by defining AST_API_MODULE just before including the header file containing the AST_OPTIONAL_API macro calls.

Note:
If the platform does not provide adequate resources, then the AST_OPTIONAL_API macro will result in a non-optional function definition; this means that any consumers of the API functions so defined will require that the provider of the API functions be loaded before they can reference the symbols.

WARNING WARNING WARNING WARNING WARNING

You MUST add the AST_MODFLAG_GLOBAL_SYMBOLS to the module for which you are enabling optional_api functionality, or it will fail to work.

WARNING WARNING WARNING WARNING WARNING

Definition in file optional_api.h.


Define Documentation

#define __stringify (  )     __stringify_1(x)

Definition at line 93 of file optional_api.h.

#define __stringify_1 (  )     #x

Definition at line 92 of file optional_api.h.

#define AST_OPTIONAL_API ( result,
name,
proto,
stub   ) 
Value:
static result __stub__##name proto stub; \
   static __attribute__((weakref(__stringify(AST_OPTIONAL_API_NAME(name))))) typeof(__stub__##name) __ref__##name; \
   static attribute_unused typeof(__stub__##name) * name; \
   static void __attribute__((constructor)) __init__##name(void) { name = __ref__##name ? : __stub__##name; }

Definition at line 197 of file optional_api.h.

#define AST_OPTIONAL_API_ATTR ( result,
attr,
name,
proto,
stub   ) 
Value:
static __attribute__((attr)) result __stub__##name proto stub; \
   static __attribute__((attr, weakref(__stringify(AST_OPTIONAL_API_NAME(name))))) typeof(__stub__##name) __ref__##name; \
   static attribute_unused __attribute__((attr)) typeof(__stub__##name) * name; \
   static void __attribute__((constructor)) __init__##name(void) { name = __ref__##name ? : __stub__##name; }

Definition at line 203 of file optional_api.h.

#define AST_OPTIONAL_API_NAME ( name   )     __##name

Definition at line 183 of file optional_api.h.

#define AST_OPTIONAL_API_UNAVAILABLE   INT_MIN

A common value for optional API stub functions to return.

This value is defined as INT_MIN, the minimum value for an integer (maximum negative value), which can be used by any optional API functions that return a signed integer value and would not be able to return such a value under normal circumstances.

Definition at line 103 of file optional_api.h.


Generated on 17 Aug 2018 for Asterisk - The Open Source Telephony Project by  doxygen 1.6.1