Programming Guides › Programming Guide for C › Tunnel Service API

Tunnel Service API

This section contains the following topics:

Tunnel Service API Overview

Develop a Custom Tunnel Service

Tunnel Service API Overview

The Tunnel Service API provides secure transfer of data between an agent and a shared library that supports the Tunnel Service.

When an agent sends a tunnel request to the Policy Server, the request contains:

• The name of the service library
• The function to be called in the service library
• The data to be passed to the function

The Policy Server initializes the appropriate service, invokes the requested function, and passes the data to the function. Once the service has performed its task, the Policy Server returns the results to the agent. The following graphic shows how the API is used in the tunnel service process:

Develop a Custom Tunnel Service

Each tunnel service is an instance of a shared library that supports the Tunnel Service API. To support a tunnel service, you must build a new shared library.

Install the shared library in one of the following locations:

• On UNIX platforms, in the SiteMinder lib directory
• On Windows platforms, in the SiteMinder bin directory

Include File

To develop a tunnel service, include the SmApi.h header file:

#include "SmApi.h"

Function Summary

The shared library must provide the following functions as externally visible entry points:

Each entry point in the shared library must be defined according to specified syntax.

Note: If you are using Microsoft Visual Studio, export the function addresses to a modular definition file (.DEF) file. To export the function addresses, create a .DEF file, and in the export section of the .DEF file, list all of the tunnel service functions, described in the previous table. Once you have created the .DEF file, add it to the Microsoft Visual Studio project.

SmQueryVersion()

SiteMinder calls this function to request the Tunnel Service API version that the custom library is compliant with.

Syntax

int SM_EXTERN SmQueryVersion (
   const Sm_Api_Context_t* lpApiContext
);

Returns

Returns the version number of the Tunnel Service API. Currently the versions supported are Sm_Api_Version_V4 and Sm_Api_Version_V4_1. Version constants are defined in SmApi.h.

SmTunnelInit()

SiteMinder calls this function so that a tunnel service can perform its own initialization procedure. This call is made once when the tunnel service is loaded for the first time. The information is cached for subsequent use.

Syntax

int SM_EXTERN SmTunnelInit (
   void**                     ppServiceHandle,
   const Sm_Api_Context_t*    lpApiContext,
   const int                  nBytesStatusBuf,
   char*                      lpszStatusBuf
);

Returns

Returns 0 if successful or -1 if unsuccessful.

SmTunnelRelease()

SiteMinder calls this function so that a tunnel service can perform its own rundown procedure. This call is made once when SiteMinder is shutting down.

Syntax

void SM_EXTERN SmTunnelRelease (
   void*                     pServiceHandle,
   const Sm_Api_Context_t*   lpApiContext
);

User-Defined Function

SiteMinder calls the function requested by the tunnel agent.

Syntax

int SM_EXTERN <func-spec> (
   void*                             pServiceHandle,
   const Sm_Api_Context_t*           lpApiContext,
   const Sm_Api_RequestContext_t*    lpReqContext,
   const Sm_Api_TunnelContext_t*     lpTunnelContext,
   const int                         nBytesInBuf,
   void*                             lpInBuf,
   const int                         nBytesOutBuf,
   void*                             lpOutBuf,
   const int                         nBytesStatusBuf,
   char*                             lpszStatusBuf
);