2.7.4 General IrisC functions

These IrisC functions are implemented by IrisSupportLib and some must also be implemented by users of IrisSupportLib.

handleMessage()

handleMessage() function.

int64_t handleMessage(void *handle_message_context, const uint64_t *message);
int64_t IrisCore_handleMessage(void *iris_core_context, const uint64_t *message);
int64_t IrisClient_handleMessage(void *iris_client_context, const uint64_t *message);

Passes a message to be routed or handled. IrisCore and IrisClient define handleMessage() functions to route a message to its destination instance by calling the handleMessage() function for that instance. If handleMessage() returns E_ok, this does not imply that a request was handled successfully or even that it has been handled at all. The response to a request is delivered by calling the handleMessage() function for the caller with a response message.

Arguments:

handle_message_context
The context pointer for the callee. For IrisCore_handleMessage(), this is the iris_core_context pointer provided by IrisCore_init(). For IrisClient_handleMessage(), this is the iris_client_context pointer provided by IrisClient_connect(). For other handleMessage() functions, this is the context pointer associated with that function.
message
A U64JSON-encoded message. This can be a request, a notification, or a response.

Return value:

An IrisErrorCode value indicating whether the call was successful.

obtainInterface()

obtainInterface() function.

int64_t obtainInterface(void *obtain_interface_context, uint64_t instId, const char *requested_interface, void **interface_ptr_out);
int64_t IrisCore_obtainInterface(void *iris_core_context, uint64_t instId, const char *requested_interface, void **interface_ptr_out);
int64_t IrisClient_obtainInterface(void *iris_client_context, uint64_t instId, const char *requested_interface, void **interface_ptr_out);

Retrieves a named native interface pointer for an instance

Arguments:

obtain_interface_context
The context pointer for the callee. For IrisCore_obtainInterface(), this is the iris_core_context pointer provided by IrisCore_init(). For IrisClient_obtainInterface(), this is the iris_client_context pointer provided by IrisClient_connect(). For other obtainInterface() functions, this should be the context pointer that is associated with that function.
instId
Instance Id of the destination instance.
requested_interface
Name of the native interface that the caller is requesting. This should be a null-terminated C string.
interface_ptr_out
*interface_ptr_out is set to the requested interface pointer.

Return value:

An IrisErrorCode value indicating whether the call was successful.

registerChannel()

registerChannel() function.

int64_t IrisCore_registerChannel(void *iris_core_context, IrisC_CommunicationChannel *channel,uint64_t *channel_id);
int64_t IrisClient_registerChannel(void *iris_client_context, IrisC_CommunicationChannel *channel,uint64_t *channel_id);

In order for IrisCore and IrisClient to route messages to an instance they must know the handleMessage() function and context pointer to use to pass a message to that instance. These pointers are grouped together into the IrisC_CommunicationChannel structure and registered with the IrisC library by calling registerChannel().

Arguments:

iris_core_context or iris_client_context
The context pointer for the callee. For IrisCore_registerChannel(), this is the iris_core_context pointer provided by IrisCore_init(). For IrisClient_registerChannel(), this is the iris_client_context pointer provided by IrisClient_connect().
channel
An IrisC_CommunicationChannel struct for the channel being registered.
channel_id
Output argument. *channel_id is set to an id number used by IrisCore or IrisClient to identify the channel. This id is used when registering instances using the instanceRegistry_registerInstance() Iris function.

Return value:

An IrisErrorCode value indicating whether the call was successful.

unregisterChannel()

unregisterChannel() function.

int64_t IrisCore_unregisterChannel(void *iris_core_context, uint64_t channel_id);
int64_t IrisClient_unregisterChannel(void *iris_core_context, uint64_t channel_id);

Unregisters a previously registered channel when an instance disconnects from the Iris system.

Arguments:

iris_core_context or iris_client_context
The context pointer for the callee. For IrisCore_unregisterChannel(), this is the iris_core_context pointer provided by IrisCore_init(). For IrisClient_unregisterChannel(), this is the iris_client_context pointer provided by IrisClient_connect().
channel_id
The id for the channel being unregistered. Any instances that have been registered using this channel are automatically unregistered if they have not already done so themselves.

Return value:

An IrisErrorCode value indicating whether the call was successful.

IrisC_CommunicationChannel structure

IrisC_CommunicationChannel structure.

struct IrisC_CommunicationChannel
{
    uint64_t CommunicationChannel_version;
    IrisC_HandleMessageFunction handleMessage_function;
    void *handleMessage_context;
    IrisC_ObtainInterfaceFunction obtainInterface_function;
    void *obtainInterface_context;
};

Members:

CommunicationChannel_version
This member must be set to 0.
handleMessage_function
handleMessage() function pointer for this channel.
handleMessage_context
Context pointer to pass when calling handleMessage_function.
obtainInterface_function
obtainInterface() function pointer for this channel. This member can be NULL if the instance does not support native interfaces.
obtainInterface_context
Context pointer to pass when calling obtainInterface_function. If obtainInterface_function is NULL, obtainInterface_context should also be NULL.

processAsyncMessages()

processAsyncMessages() function.

int64_t IrisCore_processAsyncMessages(void *iris_core_context, uint64_t flags);
int64_t IrisClient_processAsyncMessages(void *iris_client_context, uint64_t flags);

Processes any buffered messages for the current thread. If an instance is using thread marshalling to ensure that all messages are handled on the same thread, that instance must ensure that processAsyncMessages() is being called from that thread to forward marshalled messages.

Arguments:

iris_core_context or iris_client_context
The context pointer for the callee. For IrisCore_processAsyncMessages(), this is the iris_core_context pointer provided by IrisCore_init(). For IrisClient_processAsyncMessages(), this is the iris_client_context pointer provided by IrisClient_connect().
flags
Bitwise OR of IrisC_AsyncMessage flags.

Return value:

An IrisErrorCode value indicating whether the call was successful.

IrisC_AsyncMessage flags

IrisC_AsyncMessage flags.

IrisC_AsyncMessage_Default
Default non-blocking behavior. Returns immediately if there are no outstanding messages to process.
IrisC_AsyncMessage_Blocking

If there are no outstanding messages to process, block until there is one. This is useful when waiting for a response to a request. Call processAsyncMessages() as follows to wait for the response and also to avoid deadlock situations in which the recipient of your request makes a request that needs to be marshalled to the thread being blocked:

while (no_response_received)
    processAsyncMessages(context, IrisC_AsyncMessage_Blocking);

irisInitPlugin()

irisInitPlugin() function.

int64_t irisInitPlugin(IrisC_Functions *functions);

Iris plug-in entry point. This function should be exported by an Iris plug-in DSO.

Arguments:

functions
A pointer to an IrisC_Functions struct that contains pointers to IrisC functions so that the plug-in can register instances and interact with Iris.

Return value:

An error code indicating whether the call was successful.

IrisC_Functions structure

IrisC_Functions structure.

struct IrisC_Functions
{
    uint64_t Functions_version;
    void *iris_c_context;
    IrisC_RegisterChannelFunction registerChannel_function;
    IrisC_UnregisterChannelFunction unregisterChannel_function;
    IrisC_HandleMessageFunction handleMessage_function;
    IrisC_ObtainInterfaceFunction obtainInterface_function;
    IrisC_ProcessAsyncMessagesFunction processAsyncMessages_function;
};

Members:

Functions_version
This member must be set to 0.
iris_c_context
Context pointer to use when calling all IrisC functions.
registerChannel_function
Pointer to an IrisC library registerChannel() function.
unregisterChannel_function
Pointer to an IrisC library unregisterChannel() function.
handleMessage_function
Pointer to an IrisC library handleMessage() function.
obtainInterface_function
Pointer to an IrisC library obtainInterface() function.
processAsyncMessages_function
Pointer to an IrisC library processAsyncMessages() function.
Non-ConfidentialPDF file icon PDF version101196_0100_00_en
Copyright © 2018 Arm Limited or its affiliates. All rights reserved.