Asterisk - The Open Source Telephony Project GIT-master-85241bd
Macros
optional_api.h File Reference

Optional API function macros. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define AST_OPTIONAL_API(result, name, proto, stub)    result AST_OPTIONAL_API_NAME(name) proto
 Declare an optional API function. More...
 
#define AST_OPTIONAL_API_ATTR(result, attr, name, proto, stub)    result __attribute__((attr)) AST_OPTIONAL_API_NAME(name) proto
 Declare an optional API function with compiler attributes. More...
 
#define AST_OPTIONAL_API_NAME(name)   name
 Expands to the name of the implementation function. More...
 
#define AST_OPTIONAL_API_UNAVAILABLE   INT_MIN
 A common value for optional API stub functions to return. More...
 

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.

An example can be found in agi.h:

int ast_agi_register(struct ast_module *mod, agi_command *cmd)
Registers an AGI command.
Definition: res_agi.c:3815
#define AST_OPTIONAL_API_UNAVAILABLE
A common value for optional API stub functions to return.
Definition: optional_api.h:74
#define AST_OPTIONAL_API(result, name, proto, stub)
Declare an optional API function.
Definition: optional_api.h:230

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:

{
...
}
#define AST_OPTIONAL_API_NAME(name)
Expands to the name of the implementation function.
Definition: optional_api.h:228

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.

Definition in file optional_api.h.

Macro Definition Documentation

◆ AST_OPTIONAL_API

#define AST_OPTIONAL_API (   result,
  name,
  proto,
  stub 
)     result AST_OPTIONAL_API_NAME(name) proto

Declare an optional API function.

Parameters
resultThe type of result the function returns
nameThe name of the function
protoThe prototype (arguments) of the function
stubThe code block that will be used by the hidden stub when needed

Example usage:

Definition at line 230 of file optional_api.h.

◆ AST_OPTIONAL_API_ATTR

#define AST_OPTIONAL_API_ATTR (   result,
  attr,
  name,
  proto,
  stub 
)     result __attribute__((attr)) AST_OPTIONAL_API_NAME(name) proto

Declare an optional API function with compiler attributes.

Parameters
resultThe type of result the function returns
attrAny compiler attributes to be applied to the function (without the attribute wrapper)
nameThe name of the function
protoThe prototype (arguments) of the function
stubThe code block that will be used by the hidden stub when needed

Definition at line 233 of file optional_api.h.

◆ AST_OPTIONAL_API_NAME

#define AST_OPTIONAL_API_NAME (   name)    name

Expands to the name of the implementation function.

Definition at line 228 of file optional_api.h.

◆ AST_OPTIONAL_API_UNAVAILABLE

#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 74 of file optional_api.h.