HIFACE Reply Management Functions
This section contains the following reply buffer management functions of the service module, provided by libfmcsa8k.a:
SVC_GetReplyBuffer
This function is used to allocate a reply buffer of the specified length, and associate it with the token. The contents of the allocated reply buffer will be sent back to the host when SVC_SendReply() function is called.
Synopsis
#include <csa8hiface.h>ditto for all SVC functions
void *SVC_GetReplyBuffer(HI_MsgHandle token,
uint32 replyLength);
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
replyLength
|
The length of the reply buffer requested by the caller. |
Output Requirements
If the reply buffer is allocated successfully, a pointer to the allocated reply buffer is returned. Otherwise, NULL is returned.
SVC_ConvertReqToReply
This function is used to treat the request buffer as the reply buffer for in-place processing of request data. The returned address of the reply buffer is not necessarily equal to the request buffer address. However, the contents of the reply buffer will always be the same as the contents of the request buffer.
Synopsis
void *SVC_ConvertReqToReply( HI_MsgHandle token );
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
If a Reply Buffer is already allocated for the specified token, NULL is returned. Otherwise a pointer to the reply buffer is returned. The reply buffer will contain the data in the request buffer.
SVC_SendReply
This function returns the reply to the host. If there is a reply buffer associated with the token, the data recorded in reply buffer is also returned.
Synopsis
void SVC_SendReply( HI_MsgHandle token,
uint32 applicationStatus);
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
applicationStatus
|
A status code for the execution of the request, which will be reported to the host application. The values of this parameter does not affect the reply delivery in any way. |
Output Requirements
None.
SVC_ResizeReplyBuffer
This function is used to resize the reply buffer associated with the specified token. The returned address need not be equal to the previous address of the reply buffer. However, the contents of the matching parts of the old and new reply buffers will always be the same.
Synopsis
void *SVC_ResizeReplyBuffer(HI_MsgHandle token,
uint32 replyLength);
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
replyLength
|
The new length of the reply buffer requested by the Destination Module. |
Output Requirements
If the buffer is resized successfully, a pointer to the reply buffer is returned. Otherwise NULL is returned. The old reply buffer is not freed in this case.
SVC_DiscardReplyBuffer
This function is used to discard the current reply buffer. It is usually called when a processing error is detected after the reply has been allocated.
Synopsis
void SVC_DiscardReplyBuffer( HI_MsgHandle token );
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
None.
SVC_GetUserReplyBufLen
This function retrieves the length of reply buffer the host application has. If the current reply length is larger than the value returned by this function, part of the reply will be discarded on the way back.
Synopsis
uint32 SVC_GetUserReplyBufLen( HI_MsgHandle token );
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
The number of bytes available to place the reply data in the host system is returned.
SVC_GetPid
This function retrieves the process identifier (PID) recorded in the request. The PID is the Process ID of the host application that originated the request.
Synopsis
uint32 SVC_GetPid( HI_MsgHandle token );
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
The Process identifier recorded in the request is returned.
SVC_GetOid
This function retrieves the originator identifier (OID) recorded in the request. The OID is set by the host application using the MD_SendReceive() function. The value is passed in from the host application.
Synopsis
uint32 SVC_GetOid( HI_MsgHandle token );
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
The originator identifier recorded in the request is returned.
SVC_GetRequest
This function retrieves the address of request data.
Synopsis
void *SVC_GetRequest( HI_MsgHandle token );
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
The request buffer address is returned.
SVC_GetRequestLength
This function retrieves the length of request data in number of bytes.
Synopsis
uint32 SVC_GetRequestLength( HI_MsgHandle token );
Input Parameters
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
The number of bytes in the request buffer is returned.
SVC_GetReply
This function retrieves the address of current reply buffer.
Synopsis
void *SVC_GetReply( HI_MsgHandle token );
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
If there is a reply buffer associated with the token, the reply buffer address is returned. Otherwise, NULL is returned.
SVC_GetReplyLength
This function retrieves the length of reply data in number of bytes.
Synopsis
uint32 SVC_GetReplyLength( HI_MsgHandle token );
| Parameter | Description |
|---|---|
token
|
The token identifying the request. |
Output Requirements
If there is a reply buffer associated with the token, the number of bytes in the reply buffer is returned. Otherwise, 0 is returned.
