Previous Topic: Sm_AgentApi_SetSessionVariables()Next Topic: Sm_AgentApi_UnInit()

Programming Guides › Programming Guide for C › Guidance for the Agent API in C › Agent API Function Declarations (C) › Sm_AgentApi_Tunnel()

Sm_AgentApi_Tunnel()

Call this function to transfer data between a remote service on the Policy Server side and your agent. The Sm_AgentApi_GetMaxTunnelBufSize() function call gives you the maximum data size that can be transferred. At this time this function supports only one buffer for each call. pServiceRequest holds the information about the remote service that will be invoked by the Policy Server.

Note: SMTUNNEL is a predefined tunnel agent name whose shared secret is also SMTUNNEL. You can initialize a tunnel agent using these names without specifically creating the agent ahead of time. The predefined SMTUNNEL agent can only call Sm_AgentApi_Tunnel().

If you explicitly create a tunnel agent that has the name and shared secret SMTUNNEL, it is also limited to calling Sm_AgentApi_Tunnel().

If an agent named SMTUNNEL makes a call to a function other than Sm_AgentApi_Tunnel(), the Policy Server returns an error.

Syntax

int SM_EXTERN Sm_AgentApi_Tunnel (
  const void*                            pHandle,
  const int                              nServer,
  const char*                            lpszClientIpAddr,
  const char*                            lpszTransactionId,
  const Sm_AgentApi_ResourceContext_t*   pResourceContext,
  const Sm_AgentApi_TunnelServiceRequest_t* pServiceRequest,
  long*                                  pRespNumAttributes,
  Sm_AgentApi_Attribute_t**              ppRespAttributes
);

Parameter

I/O

Description

pHandle

I

Agent API session handle returned in parameter ppHandle of Sm_AgentApi_Init().

nServer

I

The server that will process the request at the time of the tunnel call. One of these values, defined in smAgentAPI.h:

/* server ports */

/* authorization server */
#define SM_AGENTAPI_AZ_SERVER 0

/* authentication server */
#define SM_AGENTAPI_AUTH_SERVER 1

/* accounting server */
#define SM_AGENTAPI_ACCT_SERVER 2

lpszClientIpAddr

I

(Optional) The IP address of the client from which the user is logging.

lpszTransactionId

I

(Optional) The ID that the agent uses to associate application activity with security activity. The Policy Server logs this ID.

pResourceContext

I

A resource definition structure.

pServiceRequest

I

A service request definition structure.

pRespNumAttributes

O

The number of attributes in ppRespAttributes.

ppRespAttributes

O

A pointer to an array of response attribute definition structures. The attribute identifier SM_AGENTAPI_ATTR_SERVICE_DATA indicates that the response structure contains the data returned by the remote service. The attribute identifier SM_AGENTAPI_ATTR_STATUS_MESSAGE has the status message from the remote service.

 

Returns

Example

For an example of Sm_AgentApi_Tunnel(), see:

<install_path>\sdk\samples\smtunnelagent\smtunnelexample.cpp