<- Metadata Go to ToC Basic API ->
2.3 High-priority Messages. 23
1 General
This Chapter specifies the API of the software library supporting this Technical Specification.
MPAI-AIF specifies the following API:
- Store API called by a Controller.
- Controller API called by a User Agent.
- Controller API called by an AIM.
- Controller API called by other Controllers.
2 Conventions
The API is written in a C-like fashion. However, the specification should be meant as a definition for a general programming language.
Note that namespaces for modules, ports and communication channels (strings belonging to which are indicated in the next sections with names such as module_name, port_name, and channel_name, respectively) are all independent.
.2.1 API types
We assume that the implementation defines several types, as follows:
| message_t | the type of messages being passed through communication ports and channels |
| parser_t | the type of parsed message datatypes (a.k.a. “the high-level protocol”) |
| error_t | the type of return code defined in 7.2.2. |
The actual types are opaque, and their exact definition is left to the Implementer. The only meaningful way to operate on library types with defined results is by using library functions.
On the other hand, the type of AIM Implementations, module_t, is always defined as:
| typedef error_t *(module_t)() |
across all implementations, in order to ensure cross-compatibility.
Types such as void, size_t, char, int, float are regular C types.
2.2 Return codes
Valid return codes:
| Code | Numeric value |
| MPAI_AIM_ALIVE | 1 |
| MPAI_AIM_DEAD | 2 |
| MPAI_AIF_OK | 0 |
Valid error codes:
| Code | Semantic value |
| MPAI_ERROR | A generic error code |
| MPAI_ERROR_MEM_ALLOC | Memory allocation error |
| MPAI_ERROR_MODULE_NOT_FOUND | The operation requested of a module cannot be executed since the module has not been found |
| MPAI_ERROR_INIT | The AIW cannot be initialied |
| MPAI_ERROR_TERM | The AIW cannot be properly terminated |
| MPAI_ERROR_MODULE_CREATION_FAILED | A new AIM cannot be created |
| MPAI_ERROR_PORT_CREATION_FAILED | A new AIM Port cannot be created |
| MPAI_ERROR_CHANNEL_CREATION_FAILED | A new Channel between AIMs could not be created. |
| MPAI_ERROR_WRITE | A generic message writing error |
| MPAI_ERROR_TOO_MANY_PENDING_MESSAGES | A message writing operation failed because there are too many pending messages waiting to be delivered |
| MPAI_ERROR_PORT_NOT_FOUND | One or both ports of a connection has (or have) been removed |
| MPAI_ERROR_READ | A generic message reading error |
| MPAI_ERROR_OP_FAILED
MPAI_ERROR_EXTERNAL_CHANNEL_CREATION_FAILED |
The requested operation failed A new Channel between Controllers could not be created. |
2.3 High-priority Messages
| Code | Numeric value |
| MPAI_AIM_SIGNAL_START | 1 |
| MPAI_AIM_SIGNAL_STOP | 2 |
| MPAI_AIM_SIGNAL_RESUME | 3 |
| MPAI_AIM_SIGNAL_PAUSE | 4 |
