RcmClient

Remote Command Message Client Module. An RcmClient is used for sending messages to an RcmServer for processing. More...

Data Structures
struct	RcmClient_Message
	Remote Command Message structure. More...
struct	RcmClient_Params
	Instance create parameters. More...
struct	RcmClient_Struct
	Opaque client structure large enough to hold an instance object. More...

Macros
#define	RcmClient_S_SUCCESS   (0)
	Success return code. More...
#define	RcmClient_E_FAIL   (-1)
	General failure return code. More...
#define	RcmClient_E_EXECASYNCNOTENABLED   (-2)
	The client has not been configured for asynchronous notification. More...
#define	RcmClient_E_EXECFAILED   (-3)
	The client was unable to send the command message to the server. More...
#define	RcmClient_E_INVALIDHEAPID   (-4)
	A heap id must be provided in the create params. More...
#define	RcmClient_E_INVALIDFXNIDX   (-5)
	Invalid function index. More...
#define	RcmClient_E_MSGFXNERROR   (-6)
	Message function error. More...
#define	RcmClient_E_IPCERROR   (-7)
	An unknown error has been detected from the IPC layer. More...
#define	RcmClient_E_LISTCREATEFAILED   (-8)
	Failed to create the list object. More...
#define	RcmClient_E_LOSTMSG   (-9)
	The expected reply message from the server was lost. More...
#define	RcmClient_E_MSGALLOCFAILED   (-10)
	Insufficient memory to allocate a message. More...
#define	RcmClient_E_MSGQCREATEFAILED   (-11)
	The client message queue could not be created. More...
#define	RcmClient_E_MSGQOPENFAILED   (-12)
	The server message queue could not be opened. More...
#define	RcmClient_E_SERVERERROR   (-13)
	The server returned an unknown error code. More...
#define	RcmClient_E_SERVERNOTFOUND   (-14)
	The server specified in the create params was not found. More...
#define	RcmClient_E_SYMBOLNOTFOUND   (-15)
	The given symbol was not found in the server symbol table. More...
#define	RcmClient_E_NOMEMORY   (-16)
	There is insufficient memory left in the heap. More...
#define	RcmClient_E_JOBIDNOTFOUND   (-17)
	The given job id was not found on the server. More...
#define	RcmClient_INVALIDFXNIDX   ((UInt32)(0xFFFFFFFF))
	Invalid function index. More...
#define	RcmClient_INVALIDHEAPID   ((UInt16)(0xFFFF))
	Invalid heap id. More...
#define	RcmClient_INVALIDMSGID   (0)
	Invalid message id. More...
#define	RcmClient_DEFAULTPOOLID   ((UInt16)(0x8000))
	Default worker pool id. More...
#define	RcmClient_DISCRETEJOBID   (0)
	Invalid job stream id. More...

Typedefs
typedef struct RcmClient_Object_tag *	RcmClient_Handle
	RcmClient instance object handle. More...
typedef Void(*	RcmClient_CallbackFxn) (RcmClient_Message *, Ptr)
	Callback function type. More...

Functions
Int	RcmClient_acquireJobId (RcmClient_Handle handle, UInt16 *jobId)
	Get a job id from the server. More...
Int	RcmClient_addSymbol (RcmClient_Handle handle, String name, Fxn addr, UInt32 *index)
	Add a symbol and its address to the server table. More...
Int	RcmClient_alloc (RcmClient_Handle handle, UInt32 dataSize, RcmClient_Message **message)
	Allocate a message from the heap configured for this instance. More...
Int	RcmClient_checkForError (RcmClient_Handle handle, RcmClient_Message **returnMsg)
	Check if an error message has been returned from the server. More...
Int	RcmClient_construct (RcmClient_Struct *structPtr, String server, const RcmClient_Params *params)
	Initialize a new instance object inside the provided structure. More...
Int	RcmClient_create (String server, const RcmClient_Params *params, RcmClient_Handle *handle)
	Create an RcmClient instance. More...
Int	RcmClient_delete (RcmClient_Handle *handlePtr)
	Delete an RcmClient instance. More...
Int	RcmClient_destruct (RcmClient_Struct *structPtr)
	Finalize the instance object inside the provided structure. More...
Int	RcmClient_exec (RcmClient_Handle handle, RcmClient_Message *cmdMsg, RcmClient_Message **returnMsg)
	Execute a command message on the server. More...
Int	RcmClient_execAsync (RcmClient_Handle handle, RcmClient_Message *cmdMsg, RcmClient_CallbackFxn callback, Ptr appData)
	Execute a command message and use a callback for notification. More...
Int	RcmClient_execCmd (RcmClient_Handle handle, RcmClient_Message *cmdMsg)
	Execute a one-way command message on the server. More...
Int	RcmClient_execDpc (RcmClient_Handle handle, RcmClient_Message *cmdMsg, RcmClient_Message **returnMsg)
	Execute a deferred procedure call on the server. More...
Int	RcmClient_execNoWait (RcmClient_Handle handle, RcmClient_Message *cmdMsg, UInt16 *msgId)
	Submit a command message to the server and return immediately. More...
Void	RcmClient_exit (Void)
	Finalize the RcmClient module. More...
Int	RcmClient_free (RcmClient_Handle handle, RcmClient_Message *msg)
	Free the given message. More...
Int	RcmClient_getSymbolIndex (RcmClient_Handle handle, String name, UInt32 *index)
	Return the function index from the server. More...
Void	RcmClient_init (Void)
	Initialize the RcmClient module. More...
Void	RcmClient_Params_init (RcmClient_Params *params)
	Initialize the instance create params structure. More...
Int	RcmClient_releaseJobId (RcmClient_Handle handle, UInt16 jobId)
	Return a job id to the server and release all resources. More...
Int	RcmClient_removeSymbol (RcmClient_Handle handle, String name)
	Remove a symbol and from the server function table. More...
Int	RcmClient_waitUntilDone (RcmClient_Handle handle, UInt16 msgId, RcmClient_Message **returnMsg)
	Block until the specified message has been executed. More...

Detailed Description

Remote Command Message Client Module. An RcmClient is used for sending messages to an RcmServer for processing.

The RcmClient module is used to send messages to an RcmServer for processing. An RcmClient instance must be created which will communicate with a single RcmServer instance. An RcmServer instance can receive messages from many RcmClient instances but an RcmClient instance can send messages to only one RcmServer instance.

Error Handling

Errors may be raised at various points in the execution flow of a single message. These are the types of errors raised by RCM:

• RCM Errors
• User Errors
• Message Function Errors
• Library Function Errors

The following diagram illustrates the call flow and highlights the points at which errors can be raised.

Diagram 1: Execution Flow

RCM errors are raised by the RCM implementation. For example, when calling RcmClient_exec(), it may raise an error if it is unable to send the message. This will be reported immediately to the caller, the server is never involved. This is highlighted in the diagram at point [A].

RCM errors may also be raised by the RcmServer. Once RcmClient_exec() sends a message, it waits for the return message. When the server receives the message, it has to decode its type. If this fails, the server records this error in the message and sends it back to the client. This is highlighted at point [B] in the diagram. When RcmClient_exec() receives the return message, it inspects the status field and recognizes the error. It then raises an appropriate error to the caller.

User errors are raised by RCM as a result of an invalid runtime condition. They are typically detected and raised by the server and then sent back to the client for processing. For example, when the server receives a message, it will lookup the function index in it's table and invoke the corresponding message function. If the index is invalid, this is detected by the server and reported as an error. The message function is never invoked. The message is returned to the client and RcmClient_exec() will raise the appropriate error. This error is raised at point [B] in the diagram.

Message function errors are raised by the message function itself. This is highlighted at point [C] in the diagram. In the body of the message function, an error is encountered either when calling a framework function or when unmarshalling the arguments from the message payload. In both cases, the message function will abort and return an error value as its return value. The error value must be less than zero (< 0). When control returns to the server, it inspects the message function's return value. If the message was sent by RcmClient_exec(), then the server simply stores the return value in the message and returns it to the client. However, if the message was send by RcmClient_execCmd(), the behavior is slightly different. If the return value is < 0 (error condition), then the server behaves the same as for the RcmClient_exec() case. However, if there is no error, the server simply frees the message. The message is never returned to the client.

Library functions errors are raised by the library functions invoked by the message function, highlighted at point [D] in the diagram. It is the responsibility of the message function to detect a library function error and to marshal the appropriate error code into the message payload. The message function must also return an error value (< 0) so that server can do proper error handing as described in the preceeding paragraph. It is the stub function's responsibility to unmarshal the error value from the message payload and take the appropriate action.

Understanding the types of errors raised by RCM and where they are raised is important when writing the upper layer software. The following code fragment illustrates how to check for the errors discussed above. See <a href"#error_handling">Error Handling above.

RcmClient_Message *msg;

// send message
status = RcmClient_exec(h, msg, &msg);

// check for error
switch (status) {

    case RcmClient_S_SUCCESS:
        // no error, all is well
        break;

    case RcmClient_E_EXECFAILED:
        // RCM error, unable to send message
        :
        break;

    case RcmClient_E_INVALIDFXNIDX:
        // user error, bad function index
        :
        break;

    case RcmClient_E_MSGFXNERROR:
        // decode message function error
        msgFxnErr = msg->result;
        :
        // decode library function error
        libFxnErr = msg->data[0];
        :
        break;
}

// free message if one was returned
if (msg != NULL) {
    RcmClient_free(h, msg);
    msg = NULL;
}

The upper layer software begins by calling RcmClient_exec() to send the message to the server. If RCM encounters a transport error and is unable to send the message, an RcmClient_E_EXECFAILED error is returned.

If the server encounters an error while decoding the message, say an invalid function index, the server returns the message and an RcmClient_E_INVALIDFXNIDX error is returned.

If the message function or the library function encounter an error, the message is returned and an RcmClient_E_MSGFXNERROR error is returned. The upper layer software must decode the results field to see what error the message function returned. If the library function returned an error, its error code must be unmarshalled from the payload. This is illustrated by decoding the first word in the payload (msg->data[0]). The actual marshal format is implementation specific.

The message function must return >=0 for success, <0 for error. Here is a very simple message function which simply turns on an LED.

Int32 Led_On(UInt32 size, UInt32 *data)
{
    Ptr led = <addr>;

    *led = 1;  // turn on LED
    return(0); // success
}

In this example, the message payload is not used. The message function does all the work, it just sets a bit in the LED control register, and returns success.

This next example illustrates a very simple RPC style skel function. It unmarshalls two arguments and invokes the libraray function. If the library function succeeds, the message function returns 0, otherwise it returns -1 to indicate failure. In both cases, the library function's return value is marshalled into the payload. The calling stub function can umarshal the return value to get the library function's error code.

Int32 MediaSkel_process(UInt32 size, UInt32 *data)
{
    Int a, b, x;
    Int32 status = 0;  // success

    // unmarshal args
    a = (Int)data[1];
    b = (Int)data[2];

    // invoke library function, returns >=0 on success
    x = Media_process(a, b);

    // marshal return value
    data[0] = (Int32)x;

    // return status
    return(x >= 0 ? 0 : -1);
}

See also

RcmServer
RCM Overview

Macro Definition Documentation

#define RcmClient_S_SUCCESS   (0)

Success return code.

#define RcmClient_E_FAIL   (-1)

General failure return code.

#define RcmClient_E_EXECASYNCNOTENABLED   (-2)

The client has not been configured for asynchronous notification.

In order to use the RcmClient_execAsync() function, the RcmClient must be configured with callbackNotification set to true in the instance create parameters.

#define RcmClient_E_EXECFAILED   (-3)

The client was unable to send the command message to the server.

An IPC transport error occurred. The message was never sent to the server.

#define RcmClient_E_INVALIDHEAPID   (-4)

A heap id must be provided in the create params.

When an RcmClient instance is created, a heap id must be given in the create params. This heap id must be registered with MessageQ before calling RcmClient_create().

#define RcmClient_E_INVALIDFXNIDX   (-5)

Invalid function index.

An RcmClient_Message was sent to the server which contained a function index value (in the fxnIdx field) that was not found in the server's function table.

#define RcmClient_E_MSGFXNERROR   (-6)

Message function error.

There was an error encountered in either the message function or the library function invoked by the message function. The semantics of the error code are implementation dependent.

#define RcmClient_E_IPCERROR   (-7)

An unknown error has been detected from the IPC layer.

Check the error log for additional information.

#define RcmClient_E_LISTCREATEFAILED   (-8)

Failed to create the list object.

#define RcmClient_E_LOSTMSG   (-9)

The expected reply message from the server was lost.

A command message was sent to the RcmServer but the reply message was not received. This is an internal error.

#define RcmClient_E_MSGALLOCFAILED   (-10)

Insufficient memory to allocate a message.

The message heap cannot allocate a buffer of the requested size. The reported size it the requested data size and the underlying message header size.

#define RcmClient_E_MSGQCREATEFAILED   (-11)

The client message queue could not be created.

Each RcmClient instance must create its own message queue for receiving return messages from the RcmServer. The creation of this message queue failed, thus failing the RcmClient instance creation.

#define RcmClient_E_MSGQOPENFAILED   (-12)

The server message queue could not be opened.

Each RcmClient instance must open the server's message queue. This error is raised when an internal error occurred while trying to open the server's message queue.

#define RcmClient_E_SERVERERROR   (-13)

The server returned an unknown error code.

The server encountered an error with the given message but the error code is not recognized by the client.

#define RcmClient_E_SERVERNOTFOUND   (-14)

The server specified in the create params was not found.

When creating an RcmClient instance, the specified server could not be found. This could occur if the server name is incorrect, or if the RcmClient instance is created before the RcmServer. In such an instance, the client can retry when the RcmServer is expected to have been created.

#define RcmClient_E_SYMBOLNOTFOUND   (-15)

The given symbol was not found in the server symbol table.

This error could occur if the symbol spelling is incorrect or if the RcmServer is still loading its symbol table.

#define RcmClient_E_NOMEMORY   (-16)

There is insufficient memory left in the heap.

#define RcmClient_E_JOBIDNOTFOUND   (-17)

The given job id was not found on the server.

When releasing a job id with a call to RcmClient_releaseJobId(), this error return value indicates that the given job id was not previously allocated with a call to RcmClient_acquireJobId().

#define RcmClient_INVALIDFXNIDX   ((UInt32)(0xFFFFFFFF))

Invalid function index.

#define RcmClient_INVALIDHEAPID   ((UInt16)(0xFFFF))

Invalid heap id.

#define RcmClient_INVALIDMSGID   (0)

Invalid message id.

#define RcmClient_DEFAULTPOOLID   ((UInt16)(0x8000))

Default worker pool id.

The default worker pool is used to process all anonymous messages. When a new message is allocated, the pool id property is initialized to this value.

#define RcmClient_DISCRETEJOBID   (0)

Invalid job stream id.

All discrete messages must have their jobId property set to this value. When a new message is allocated, the jobId property is initialized tothis value.

Typedef Documentation

typedef struct RcmClient_Object_tag* RcmClient_Handle

RcmClient instance object handle.

typedef Void(* RcmClient_CallbackFxn) (RcmClient_Message *, Ptr)

Callback function type.

When using callback notification, the application must supply a callback function of this type. The callback will be invoked with the pointer to the RcmClient_Message returned from the server and the application data pointer supplied in the call to RcmClient_execAsync().

Function Documentation

Int RcmClient_acquireJobId	(	RcmClient_Handle	handle,
		UInt16 *	jobId
	)

Get a job id from the server.

Acquire a unique job id from the server. The job id is used to associate messages with a common job id. The server will process all messages for a given job id in sequence.

Int RcmClient_addSymbol	(	RcmClient_Handle	handle,
		String	name,
		Fxn	addr,
		UInt32 *	index
	)

Add a symbol and its address to the server table.

This function is used by the client to dynamically load a new function address into the server's function pointer table. The given address must be in the server's address space. The function must already be loaded into the server's memory.

This function is useful when dynamically loading code onto the remote processor (as in the case of DLL's).

Parameters

[in]	handle	Handle to an instance object
[in]	name	The function's name.
[in]	addr	The function's address as specified in the remote processor's address space.
[out]	index	The function's index value to be used in the RcmClient_Message.fxnIdx field.

Return values

RcmClient_S_SUCCESS	Success
RcmClient_E_FAIL	Failure

Int RcmClient_alloc	(	RcmClient_Handle	handle,
		UInt32	dataSize,
		RcmClient_Message **	message
	)

Allocate a message from the heap configured for this instance.

When a message is allocated, the RcmClient instance is the owner of the message. All messages must be returned to the heap by calling RcmClient_free().

During a call to all of the exec functions, the ownership of the message is temporarily transfered to the server. If the exec function returns an RcmClient_Message pointer, then ownership of the message is returned to the instance. For the other exec functions, the client acquires ownership of the return message by calling RcmClient_waitUntilDone().

A message should not be accessed when ownership has been given away. Once ownership has been reacquired, the message can be either reused or returned to the heap.

Parameters

[in]	handle	Handle to an instance object
[in]	dataSize	Specifies (in chars) how much space to allocate for the RcmClient_Message.data array. The actual memory allocated from the heap will be larger as it includes the size of the internal message header.
[out]	message	A pointer to the allocated message or NULL on error.

Int RcmClient_checkForError	(	RcmClient_Handle	handle,
		RcmClient_Message **	returnMsg
	)

Check if an error message has been returned from the server.

When using RcmClient_execCmd() to send messages to the server, the message will be freed by the server unless an error occurs. In the case of an error, the message is returned to the client. Use this function to check for and to retrieve these error messages.

Note that the latency of the return message is dependent on many system factors. In particular, the server's response time to processing a message will be a significant factor. It is possible to call RcmClient_execCmd() several times before any error message is returned. There is no way to know when all the messages have been processed.

The return value of RcmClient_checkForError() is designed to mimic the return value of RcmClient_exec(). When an error message is returned to the caller, the return value of RcmClient_checkForError() will be the appropriate error code as if the error had occured during a call to RcmClient_exec(). For example, if a message is prepared with an incorrect function index, the return value from RcmClient_exec() would be RcmClient_E_INVALIDFXNIDX. However, the same message sent with RcmClient_execCmd() will not return an error, because the function does not wait for the return message. When the server receives the message and detects the function index error, it will return the message to the client on a special error queue. The subsequent call to RcmClient_checkForError() will pickup this error message and return with a status value of RcmClient_E_INVALIDFXNIDX, just as the call to RcmClient_exec() would have done.

A return value of RcmClient_S_SUCCESS means there are no error messages. This function will never return a message and a success status code at the same time.

When this function returns an error message, the caller must return the message to the heap by calling RcmClient_free().

It is possible that RcmClient_checkForError() will return with an error but without an error message. This can happen when an internal error occurs in RcmClient_checkForError() before it has checked the error queue. In this case, an error is returned but the returnMsg argument will be set to NULL.

Parameters

[in]	handle	Handle to an instance object
[out]	returnMsg	A pointer to the error message or NULL if there are no error messages in the queue.

Return values

RcmClient_S_SUCCESS
RcmClient_E_IPCERROR
RcmClient_E_INVALIDFXNIDX
RcmClient_E_MSGFXNERROR
RcmClient_E_SERVERERROR

Int RcmClient_construct	(	RcmClient_Struct *	structPtr,
		String	server,
		const RcmClient_Params *	params
	)

Initialize a new instance object inside the provided structure.

This function is the same as RcmClient_create() except that it does not allocate memory for the instance object. The instance object is constructed inside the provided structure. Call RcmClient_destruct() to finalize a constructed instance object.

Parameters

[in]	structPtr	A pointer to an allocated structure.
[in]	server	The name of the server that messages will be sent to for executing commands. The name must be a system-wide unique name.
[in]	params	The create params used to customize the instance object.

See also

RcmClient_create

Int RcmClient_create	(	String	server,
		const RcmClient_Params *	params,
		RcmClient_Handle *	handle
	)

Create an RcmClient instance.

The RcmClient instance is used by the application to send messages to an RcmServer for executing remote functions. A given instance can send messages only to the server it was configured for. If an application needs to send messages to multiple servers, then create an RcmClient instance for each server.

The assigned server to this instance must already exist and be running before creating RcmClient instances which send messages to it.

Parameters

[in]	server	The name of the server that messages will be sent to for executing commands. The name must be a system-wide unique name.
[in]	params	The create params used to customize the instance object.
[out]	handle	An opaque handle to the created instance object.

Int RcmClient_delete

(

RcmClient_Handle *

handlePtr

)

Delete an RcmClient instance.

Parameters

[in,out]

handlePtr

Handle to the instance object to delete.

Int RcmClient_destruct

(

RcmClient_Struct *

structPtr

)

Finalize the instance object inside the provided structure.

Parameters

[in]

structPtr

A pointer to the structure containing the instance object to finalize.

Int RcmClient_exec	(	RcmClient_Handle	handle,
		RcmClient_Message *	cmdMsg,
		RcmClient_Message **	returnMsg
	)

Execute a command message on the server.

The message is sent to the server for processing. This call will block until the remote function has completed. When this function returns, the message will contain the return value of the remote function as well as a possibly modified context.

After calling exec, the message can be either reused for another call to exec or it can be freed.

Parameters

[in]	handle	Handle to an instance object
[in]	cmdMsg	Pointer to an RcmClient_Message structure.
[out]	returnMsg	A pointer to the return message or NULL on error. The client must free this message. The return value of the message function is stored in the results field. The return value of the library function is marshalled into the data field.

Return values

RcmClient_S_SUCCESS
RcmClient_E_EXECFAILED
RcmClient_E_INVALIDFXNIDX
RcmClient_E_LOSTMSG
RcmClient_E_MSGFXNERROR
RcmClient_E_SERVERERROR

Int RcmClient_execAsync	(	RcmClient_Handle	handle,
		RcmClient_Message *	cmdMsg,
		RcmClient_CallbackFxn	callback,
		Ptr	appData
	)

Execute a command message and use a callback for notification.

The message is sent to the server for execution, but this call does not wait for the remote function to execute. This call returns as soon as the message has been dispatched to the transport. Upon returning from this function, the ownership of the message has been lost; do not access the message at this time.

When the remote function completes, the given callback function is invoked by this RcmClient instance's callback server thread. The callback function is used to asynchronously notify the client that the remote function has completed.

The RcmClient instance must be create with callbackNotification set to true in order to use this function.

Parameters

[in]	handle	Handle to an instance object
[in]	cmdMsg	Pointer to an RcmClient_Message structure.
[in]	callback	A callback function pointer supplied by the application. It will be invoked by the callback server thread to notify the application that the remote function has completed.
[in]	appData	A private data pointer supplied by the application. This allows the application to provide its own context when receiving the callback.

Int RcmClient_execCmd	(	RcmClient_Handle	handle,
		RcmClient_Message *	cmdMsg
	)

Execute a one-way command message on the server.

The message is sent to the server for processing but this function does not wait for the return message. This function is non-blocking. The server will processes the message and then free it, unless an error occurs. The return value from the remote function is discarded.

If an error occurs on the server while processing the message, the server will return the message to the client. Use RcmClient_checkForError() to collect these return error messages.

When this function returns, ownership of the message has been transfered to the server. Do not access the message after this function returns, it could cause cache inconsistencies or a memory access violation.

Parameters

[in]	handle	Handle to an instance object
[in]	cmdMsg	Pointer to an RcmClient_Message structure.

Return values

RcmClient_S_SUCCESS
RcmClient_E_IPCERROR

Int RcmClient_execDpc	(	RcmClient_Handle	handle,
		RcmClient_Message *	cmdMsg,
		RcmClient_Message **	returnMsg
	)

Execute a deferred procedure call on the server.

The return field of the message is not used.

Parameters

[in]	handle	Handle to an instance object
[in]	cmdMsg	Pointer to an RcmClient_Message structure.
[out]	returnMsg	A pointer to the return message or NULL on error. The client must free this message.

Int RcmClient_execNoWait	(	RcmClient_Handle	handle,
		RcmClient_Message *	cmdMsg,
		UInt16 *	msgId
	)

Submit a command message to the server and return immediately.

The message is sent to the server for execution but this call does not wait for the remote function to execute. The call returns as soon as the message has been dispatched to the transport. Upon returning from this function, the ownership of the message has been lost; do not access the message at this time.

Using this call to execute a remote message does not require a callback server thread. The application must call RcmClient_waitUntilDone() to get the return message from the remote function.

Parameters

[in]	handle	Handle to an instance object
[in]	cmdMsg	A pointer to an RcmClient_Message structure.
[out]	msgId	Pointer used for storing the message id. Use the message id in a call to RcmClient_WaitUntilDone() to retrieve the return value of the remote function.

Void RcmClient_exit

(

Void

)

Finalize the RcmClient module.

This function is used to finalize the RcmClient module. Any resources acquired by RcmClient_init() will be released. Do not call any RcmClient functions after calling RcmClient_exit().

This function must be serialized by the caller.

Int RcmClient_free	(	RcmClient_Handle	handle,
		RcmClient_Message *	msg
	)

Free the given message.

Parameters

[in]	handle	Handle to an instance object
	msg	Pointer to an RcmClient_Message structure.

Int RcmClient_getSymbolIndex	(	RcmClient_Handle	handle,
		String	name,
		UInt32 *	index
	)

Return the function index from the server.

Query the server for the given function name and return its index. Use the index in the fxnIdx field of the RcmClient_Message struct.

Parameters

[in]	handle	Handle to an instance object
[in]	name	The function's name.
[out]	index	The function's index.

Void RcmClient_init

(

Void

)

Initialize the RcmClient module.

This function is used to initialize the RcmClient module. Call this function before calling any other RcmClient function.

This function must be serialized by the caller

Void RcmClient_Params_init

(

RcmClient_Params *

params

)

Initialize the instance create params structure.

Int RcmClient_releaseJobId	(	RcmClient_Handle	handle,
		UInt16	jobId
	)

Return a job id to the server and release all resources.

Parameters

[in]	handle	Handle to an instance object
[in]	jobId	The job id to be released

Int RcmClient_removeSymbol	(	RcmClient_Handle	handle,
		String	name
	)

Remove a symbol and from the server function table.

Useful when unloading a DLL from the server.

Parameters

[in]	handle	Handle to an instance object
[in]	name	The function name.

Int RcmClient_waitUntilDone	(	RcmClient_Handle	handle,
		UInt16	msgId,
		RcmClient_Message **	returnMsg
	)

Block until the specified message has been executed.

This function will wait until the remote function invoked by the specified message has completed. Upon return from this call, the message will contain the return value and the return context of the remote function.

Parameters

[in]	handle	Handle to an instance object
[in]	msgId	The message ID to wait for.
[out]	returnMsg	A pointer to the return message or NULL on error. The client must free this message.