6.1 Introduction

6.2 Declaring SPI Function Prototypes

6.3 Implementing the SPI Functions

6.3.1 DISP_COMMAND Structure

6.3.2 Marshalling

6.3.3 Example SPI Function

6.1 Introduction

Implementing the SPI includes:

• Declaring SPI function prototypes

• Implementing the SPI functions

The following files are created or modified when implementing the service SPI:

File	Description
xxxspi.c	Implements the service SPI functions.
xxxspi.h	Contains SPI prototypes.

6.2 Declaring SPI Function Prototypes

The service header file, xxxspi.h, contains the function prototype for each SPI function.

The signature of an SPI function is typically almost identical to that of its associated API function, except the SPI function contains an additional parameter to indicate the invoker of the SPI function. This value may be a service ID (if the SPI function is called by another service) or CTA_APP_SVCID (if the SPI function is called by an API function).

tik service

<<<< excerpt from tikspi.h >>>> /*---------------------------------------------------------- SPI function for tikStartTimer API. ----------------------------------------------------------*/ DWORD NMSAPI tikSpiCmdStartTimer( CTAHD ctahd, TIK_START_PARMS *start, WORD source) ;

6.3 Implementing the SPI Functions

Each service API function has a corresponding SPI function in the file xxxspi.c. The SPI function marshals the parameters into an SPI command message structure (DISP_COMMAND) and calls dispSendCommand to send the command to the service implementation (as shown in Figure 23). When the reply is received, the SPI function unmarshals the results (if any).

Figure 23. Service SPI Functionality

6.3.1 DISP_COMMAND Structure

The SPI function marshals the parameters into the command message structures (DISP_COMMAND). The DISP_COMMAND structure contains the following fields:

typedef struct
{
  DWORD id;      /*Command ID (and dest. service ID)            */
  CTAHD ctahd;      /*CT Access context handle            */
  DWORD size1;      /*If dataptr1 !=NULL => size1 is buffer            */
        /*size - else message specific data            */
  void *dataptr1;      /*Data pointer            */
  DWORD size2;       /*If dataptr2 !=NULL => size2 is buffer            */
        /*size - else message specific data            */
  void *dataptr2;      /*Data pointer            */
  DWORD size3;      /*If dataptr3 !=NULL => size3 is buffer            */
        /*size - else message specific data            */
  void *dataptr3;       /*Data pointer            */
  DWORD reserved;      /*Must be zero (0).            */
  MESSAGE_ADDR addr;     /*Source/Destination service ID             */
} DISP_COMMAND;

typedef struct
{
  WORD source          /* source service ID */
  WORD destination     /* destination service ID */
} MESSAGE_ADDR

The following section describes how to marshal data into and out of this structure.

6.3.2 Marshalling

Marshalling is the conversion of the SPI function call into a DISP_COMMAND message. The messages are currently not converted to network byte order (for efficiency).

Up to 3 "arguments" may be packed into a message. If an API has more formal arguments, then internal structure(s) must be created to hold the formal arguments (i.e., collapse arguments into transport structures). For example, if there are five required arguments, create an internal data structure that contains three of the arguments.

Arguments are passed in size/data pointer pairs. If the data pointer is NULL, then the size field contains data. Otherwise, the size field is the size of the buffer holding the arguments pointed to by the data pointer.

For out parameters which are passing a buffer to be filled in by a service implementation, "logically or" in the CTA_VIRTUAL_BUF flag (see tikGetChannelInfo). This is an optimization for buffer handling to speed up processing.

In the SPI function, service parameter arguments must be checked for NULL value and the appropriate size and dataptr fields set accordingly.

6.3.3 Example SPI Function

tik service

<<<< excerpt from tikspi.h >>>> DWORD NMSAPI tikSpiCmdStartTimer( CTAHD ctahd, TIK_START_PARMS *start, WORD source ) { void *dataptr1; DWORD size1; DISP_COMMAND m; if ( start != NULL ) { /* Use application supplied TIK parameters. */ size1 = start->size; dataptr1 = (void *)start; } else { /* Use TIK parameter default values stored in CT Access.*/ size1 = 0; dataptr1 = NULL; } /* Marshal function id, function arguments, destination * service, and source identifier into message buffer. */ m.id = TIKCMD_START; m.ctahd = ctahd; m.size1 = size1; m.dataptr1 = (dataptr1); m.size2 = 0; m.dataptr2 = NULL; m.size3 = 0; m.dataptr3 = NULL; m.reserved = 0; m.addr.destination = TIK_SVCID; m.addr.source = source; /* Send command to TIK service via CT Access dispatcher. */ return dispSendCommand(&m); }