Programming Guides › Programming Guide for C › Event API Guidance

Event API Guidance

This section contains the following topics:

Event API Overview

Event API Setup

Event Provider Structures

Event API Reference

Event Function Declarations

Example of an Active Policy

Configuring the Policy Server for the Event Handler

Event API Overview

The SiteMinder Event API lets you create custom event handlers.

Through the Event API, SiteMinder can log events using outside sources, providers, or applications. You can then access the logged information through these other sources, providers, or applications.

Using the Event API, you can build applications to alert administrators of SiteMinder activity. For example, an event handler can send an e-mail to the administrator when the accounting server starts or someone creates a new policy.

Event API Setup

Each event handler is an instance of a shared library that supports the Event API provider interface. To support custom event handlers, you must build a 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

The shared library must export the following entry points:

SmEventInit()
SmEventRecord()
SmEventRelease()

To build an event handler, include the SmEventApi.h header file:

#include "SmEventApi.h"

Event Provider Structures

The following table lists the structure definitions used with Event Provider API functions:

Structure	Description
SmLog_Access_t	Contains information about access events.
SmLog_EMS_t	Contains information about Entitlement Management Services (EMS) events. EMS events result from actions performed on directory objects.
SmLog_Obj_t	Contains information about object events.
SmLog_System_t	Contains information about system events.

SmLog_Access_t

Contains information about an access event.

Syntax

typedef struct SmLog_Access_s
{
   long nVersion;
   long nCurrentTime;
   Sm_Api_Reason_t nReason;
   char* szAgentName;
   char* szSessionId;
   char* szClientIp;
   char* szUserName;
   char* szDomainOid;
   char* szRealmName;
   char* szRealmOid;
   char* szAuthDirName;
   char* szAuthDirServer;
   char* szAuthDirNamespace;
   char* szServer;
   char* szResource;
   char* szAction;
   char* szTransactionId;
   char* szStatusMsg;
   char* szDomainName;
   char* szImpersonatorName;
   char* szImpersonatorDirName;
} SmLog_Access_t;

Field	Description
nVersion	Version number of the Policy Server.
nCurrentTime	Policy Server time (in GMT) when the event occurred.
nReason	Contains the reason identifier.
szAgentName	Name of the agent.
szSessionId	Session ID.
szClientIp	The IP address of the client.
szUserName	Full distinguished name of the user or administrator.
szDomainOid	The object identifier of the domain object.
szRealmName	Name of the realm in which the resource is protected.
szRealmOid	Object identifier for the realm object.
szAuthDirName	The name of the directory.
szAuthDirServer	Directory Server of a SiteMinder user directory where user’s context was established.
szAuthDirNamespace	Directory Namespace such as LDAP, WinNT, or ODBC.
szServer	Name of the server holding the resource.
szResource	Name of the resource.
szAction	Type of action performed on the resource. A typical action when accessing web resources is a GET.
szTransactionId	Identifier of a transaction between the agent and Policy Server. The agent sets this ID and the Policy Server logs it. When the agent makes a request to the Policy Server, it associates an ID with the request. Since the agent may make many such requests, the agent uses the ID to match information from the Policy Server with the originating request.
szStatusMsg	Status message.
szImpersonatorName	Specifies the name of the impersonator. Set to NULL if there is no impersonated session in progress.
szDomainName	Specifies the name of the domain.
szImpersonator DirName	Specifies the name of the user directory used to authenticate the impersonator. Set to NULL if there is no impersonated session in progress.

More Information:

Sm_Api_Reason_t

SmLog_EMS_t

Contains information about an Entitlement Management Services (EMS) event. EMS events result from actions performed on directory objects.

Syntax

typedef struct SmLog_EMS_s
{
   long nVersion;
   long nCurrentTime;
   char* szUserName;
   char* szSessionId;
   char* szDirName;
   char* szObjName;
   char* szObjPath;
   char* szObjClass;
   char* szOrgName:
   char* szRoleName;
   int   szFieldDesc;
   char* szStatusMsg;
} SmLog_EMS_t;

Field	Description
nVersion	Version number of the Policy Server.
nCurrentTime	Policy Server time (in GMT) when the event occurred.
szUserName	If the user is an administrator, the ID of the administrator who initiated the EMS event. If the event is an end-user event, the user name is Registration.
szSessionID	EMS Service Session ID.
szDirName	Name of the SiteMinder directory affected by the EMS event.
szObjName	Name of the object targeted by this event.
szObjPath	Full distinguished name of the object.
szObjClass	Class name of the object.
szOrgName	Name of the object’s organization.
szRoleName	Name of the role to which the object is related (only for events that involve roles).
szFieldDesc	Description of the event.
szStatusMsg	The status message.

SmLog_Obj_t

Contains information about an object event.

Syntax

typedef struct SmLog_Obj_s
{
   long nVersion;
   long nCurrentTime;
   char* szUserName;
   char* szSessionId;
   char* szDomainOid;
   char* szObjName;
   char* szObjOid;
   char* szFieldDesc;
   char* szStatusMsg;
} SmLog_Obj_t;

Field	Description
nVersion	Version number of the Policy Server.
nCurrentTime	Policy Server time (in GMT) when the event occurred.
szUserName	The name of the user who triggered the event.
szSessionId	Session ID.
szDomainOid	Object identifier for the domain object.
szObjName	The name of the object.
szObjOid	Object identifier for the object.
szFieldDesc	User DN.
szStatusMsg	Status message.

SmLog_System_t

Contains information about a system event.

Syntax

typedef struct SmLog_System_s
{
   long nVersion;
   long nCurrentTime;
   char* szName;
   char* szIpAddress;
   int   nIpPort;
   char* szMsg;
} SmLog_System_t;

Field	Description
nVersion	Version number of the Policy Server.
nCurrentTime	Time when the event occurred.
szName	Name of the client, database, or directory.
szIpAddress	IP address of the client.
nIpPort	Port number that the client communicates on.
szMsg	Buffer to receive string message for an event.