C Plug-In Tap Point Interface

Your Webtrends C plug-in should use the following functions:

• XltInitialize
• XltOpenSession
• XltTranslate
• XLTTranslateVisitorHit (optional)
• XLTTranslateVisitorSession (optional)
• XltCloseSession
• XltTerminate

When Webtrends Analysis Engines or the Event Database Loader loads the plug-in, it attempts to get function pointers for each of the five required functions. If any function pointer is not available, the plug-in is not loaded.

The following pseudo-code shows the order in which the plug-in’s functions are used.

Load the plug-in;
Get function pointers to the functions;
XltInitialize ();
XltOpenSession ();
For each record
    {
    XltTranslate ();
    XltTranslateVisitorHit ();
    XltTranslateVisitorSession (); 
    }
XltCloseSession ();
XltTerminate ();

The following sections describe each of these functions.

Analysis Tap Points

The following table shows the functions called at each analysis tap point.

XltInitialize

The XltInitialize function initializes your plug-in. If plug-in initialization succeeds, the function returns XLTOK and sets the output parameters. When the output parameters are set, the plug-in is successfully initialized and ready to open sessions. If XltInitialize returns XLTERR, the plug-in is not used until this function returns XLTOK.

Parameters

The following output parameters are set:

lpdwMajorVersion
Specifies the major version of the plug-in. In the version 1.5, 1 is the major version.

lpdwMinorVersion
Specifies the minor version of the plug-in. In the version 1.5, 5 is the minor version.

lpdwPluginType
Specifies whether the plug-in works with log file records or with Web Data Warehouse records. Set this parameter to CybRecAdapterType if you want to use the plug-in for log file data. Set this parameter to WebHouseAdapterType if you want to use the plug-in with Webtrends Web Data Warehouse data. For example, *lpdwPluginType = CybRecAdapterType;

lplpszName
Specifies the name of the plug-in.

Function Specification

DLL_EXPORT INT XltInitialize (
    LPCSTR lpszProgramPath, // In
    LPDWORD lpdwMajorVersion, // Out
    LPDWORD lpdwMinorVersion, // Out
    LPDWORD lpdwPluginType, // Out
    LPCSTR *lplpszName); // Out

XltOpenSession

After the XltInitialize function returns XLTOK, Webtrends calls the XltOpenSession function.

Inputs

lpfnResolveName
Callback function that your plug-in uses to request data from Webtrends. Store lpfnResolveName globally so it can be used in the XltTranslate function. For more information, see the “ResolveName” section in the article "C Plug-In Callback Interface."

lpfnApplyTranslation
Callback function that changes the data requested. Store lpfnApplyTranslation globally so it can be used in the XltTranslate function. For more information, see the “ApplyTranslation" section of the article "C Plug-In Callback Interface."

lpszSessionDetails
Contains AppGetValue and AppSetValue callback functions which are used internally by Webtrends. Your plug-in does not need to use these functions. For more information, see the comments in the translate.h file.

Returns

XLT_SESSIONID_T
Specifies the plug-in session context handle that should be passed in with every subsequent function API call. The plug-in should save the application's context handle, along with any other session-based details it requires in a structure/object and return a pointer to that structure back to the caller. A value of NULL indicates failure.

Function Specification

DLL_EXPORT XLT_SESSIONID_T XltOpenSession (
    lpfnResolveName_T lpfnResolveName,
    lpfnApplyTranslation_T lpfnApplyTranslation,
    LP_SESION_INFO_T lpszSessionDetails);

XltTranslate

After a successful return from the XltOpenSession function, Webtrends calls the XltTranslate function. This function allows the plug-in to translate a log file record.

Inputs

tsSessionID
Specifies the session ID that was set in the xltOpenSession function.

lpDetails
Details about the log file record. To be passed to the ResolveName() and ApplyTranslation() callbacks into the application.

Returns

XLTOK
Indicates that the translation was successful.

XLTERR
Indicates that the translation was not successful.

XLTFILTER
Indicates that the plug-in requested this hit should be excluded from analysis.

Function Specification

DLL_EXPORT int XltTranslate (
    XLT_SESSIONID_T tsSessionID,
    void lpDetails);

XltTranslateVisitorHit

Webtrends calls the xltTranslateVisitorHit function after xltTranslate completes successfully. This function allows the plug-in to translate a log file record after the hit is processed.

This function is not available for Basic Analysis plug-ins and is optional for Standard Analysis and Visitor Data Mart plug-ins.

Inputs

tsSessionID
Specifies the session ID that was set in the xltOpenSession function.

lpDetails
Details about the log file record. To be passed to the lpfnResolveName_T() and lpfnApplyTranslation_T() callbacks into the application.

nHitSessionId
Unique ID for the visitor session this hit belongs to. This is valid until the session is completed and through the VisitorSession tap point (XltTranslateVisitorSession)

lpszSession
Cookie visitor ID if it is available. It may not be available for all session hits. It will be identical to XltTranslateVisitorSession::lpszVisitorId.

fNewVisitorSession
Indicates that it is the first hit of a new visitor session.

Returns

XLTOK
Indicates that the translation was successful.

XLTERR
Indicates that the translation not successful.

Function Specification

DLL_EXPORT int XltTranslateVisitorHit
    XLT_SESSIONID_T tsSessionID,
    void lpDetails, 
    unsigned nHitSessionId,
    const char lpszSessionId, 
    bool fNewVisitorSession);

XltTranslateVisitorSession

After the XltTranslateVisitorHit() function has completed successfully, Webtrends calls the xltTranslateVisitorSession function. This function allows the plug-in to translate visitor session information.

This function is not available for Visitor Data Mart plug-ins.

Input

tsSessionID
The session ID that was set in the xltOpenSession function.

lpDetails
Details about the visitor session record to be passed to ResolveName_T() and ApplySessionTranslation_T() callbacks into Webtrends.

nHitSessionId
Specifies the unique ID for the visitor session. This corresponds to the nHitSessionId used in XltTranslateVisitorHit().

lpszVisitorId
Persistent unique ID for the visitor.

Returns

XLTOK
Indicates that the translation was successful.

XLTERR
Indicates that the translation not successful.

Function Specification

DLL_EXPORT int XltTranslateVisitorSession (
    XLT_SESSIONID_T tsSessionID,
    void lpDetails,
    unsigned nHitSessionId,
    const char lpszVisitorId); 

XltCloseSession

Webtrends calls this function at the completion of the plug-in’s session. After this function is called, there are no more calls to XltTranslate, xltTranslateVisitorHit, or xltTranslateVisitorSession for this plug-in session ID.

Input

tsSessionID
Specifies the session ID that was set in the xltOpenSession function.

Returns

void
Returns a value of void to close the session.

Function Specification

DLL_EXPORT void XltCloseSession (
    XLT_SESSIONID_T tsSessionID);

XltTerminate

The xltTerminate function stops the plug-in. The plug-in should close any open sessions, clean up any resources used, and be prepared for a call to XltInitialize.

Function Specification

DLL_EXPORT void XltTerminate ();