MD_SendReceive

This function is used to send a request and receive the response.

Synopsis

#include <md.h>
MD_RV MD_SendReceive(uint32 hsmIndex,
                     uint32 originatorId,
                     uint16 fmNumber,
                     MD_Buffer_t* pReq,
                     uint32 timeout,
                     MD_Buffer_t* pResp,
                     uint32* pReceivedLen,
                     uint32* pFmStatus);  

Input Requirements

The message dispatch library has been initialized via the MD_Initialize() function.

Input Parameters

Parameter

Description

hsmIndex

Zero-based index of the HSM to query. For remote HSMs, HSMs are numbered according to the order that the HSMs' IP addresses were entered in the ET_HSM_NETCLIENT_SERVERLIST registry key. Refer to the SafeNet HSM Access Provider Installation Guide for further details. When MD_Initialize() is invoked, the message dispatch library assigns an index to each available HSM.

fmNumber

Identifies whether the request is intended for a Functionality Module(FM) or not. This value must be set to FM_NUMBER_CUSTOM_FM (#include csa8fm.h).

originatorId

ID of the request originator. This value is typically 0. The value should only be non-zero when the calling application is acting as a proxy.

pReq

Array of request buffers to send to the FM module. For user-defined functions, the structure and content of the array of buffers is user-defined. Refer to javahsmreset and javahsmstate for an example of how to construct the response and request buffers for a user-defined function in Java.

Each buffer in the array is an MD_Buffer_t struct, which contains a pointer to the data and the number of bytes of data, as detailed below.

typedef struct
{
uint8*pData;
unit32length;
} MD_Buffer_t;  

In the final MD_Buffer_t struct the pData field must contain a NULL pointer and the length field should be set to 0. This indicates the end of the array of buffers. This scheme allows arrays with variable number of buffers to be passed into the function.

The following diagram illustrates an array of buffers containing two buffers. The first buffer contains 6 bytes of data and the second buffer contains 4 bytes of data. The last array element contains an array with the pData field set to NULL and the length field set to 0 to indicate the end of the array.

Figure 1: An example of a request buffers data type for function MD_SendReceive

timeout

The message timeout in ms. If set to 0, an internal default of 10 minutes is used. 

pResp

Response buffers. When the function returns, the response from the FM is contained in these buffers. Refer to the description of the pReq buffers above for details on how these buffers must be constructed.

The memory for the pResp buffers must be allocated in the context of the application which calls the function. The pData field and length fields must be assigned appropriately to conform to the anticipated response packet.

The buffers are filled in order until either the entire response is copied or the buffers overflow (this condition determined by pReceivedLen, described below).

The value of this parameter can be NULL if the FM function will not return a response.

pReceivedLen

Address of variable to hold the total number of bytes placed in the response buffers. The memory for this variable must be allocated in the context of the application which calls the function. The value of this parameter can be NULL if the FM function will not return a response.

pFmStatus

Address of variable to hold the status/return code of the Functionality Module which processed the request. The meaning of the value is defined by the FM. The value of this parameter can be NULL.

Output Requirements

The request is sent to the appropriate FM module. Where applicable the response is returned in the response buffers.

The function returns the following codes:

Function Code

Qualification

MDR_OK

N/A

MDR_UNSUCCESSFUL

N/A

MDR_INVALID_PARAMETER

If the pointer supplied for pReq is NULL, if the request requires a response and the pointer supplied for pResp is NULL or if pReserved is not zero.

MDR_NOT_INITIALIZE

If the message dispatch library was not previously initialized successfully.

MDR_INVALID_HSM_INDEX

If HSM index was not in the range of accessible HSMs.

MDR_INSUFFICIENT_RESOURCE

If there is insufficient memory on either the host or adapter

MDR_OPERATION_CANCELLED

The operation was cancelled in the HSM. This code will not be returned.

MDR_INTERNAL_ERROR

The HSM has detected an internal error. This code will be returned if there is a fault in the firmware or device driver.

MDR_ADAPTER_RESET

The HSM was reset during the operation. This could be possibly due to the MD_ResetHsm command being issued during the operation.

MDR_FM_NOT_AVAILABLE

An invalid FM number was used.