VgwSessionNewFnc


Use the VgwSessionNewFnc function to set a context for a session and perform other initialization. The Verity engine calls your VgwSessionNew function when a collection is opened or a document source is created.


Syntax

VdkError VgwSessionNewFnc(
   VgwSessionNewArg   vgwSessionNewArg,
   VgwAppSession*     pvgwSession)

Arguments

 


vgwSessionNewArg

VgwSessionNewArg   A reference to a VgwSessionNewArgRec structure, which is provided as input and is populated by the Verity engine.

pvgwSession

VgwAppSession*   A handle to data available to each of your callback functions that are associated with a session.


Member Descriptions

 

Table 3-1    VgwSessionNewArgRec Members


Member

Type/Description

sessAppData

VdkVoidp   Gateway-defined data.

drvAppData

VdkCBArg   The driver handle that contains your driver’s global data, which was set in your driver’s VdkDrvNewCBFnc function.

vdkSession

VdkSession   The VDK session handle.

collection

VdkCollection   A Verity collection handle if the session is associated with a collection.

docSource

VdkDocSource   A Verity document source handle if the session is associated with a document source.

configDirectory

VdkCString   A style directory that contains the gateway configuration files.

configuration

VdkCString   Configuration specification whose value is supplied from the configuration statement in the collection’s style.vgw file.

callbackList

AppCBList*   Deprecated; do not use.

securityModelMask

VdkInt4   Bitmask of authentication and ACL requests ANDed with the capabilities of the gateway.

securityModuleId

VdkUint2   Security model for this session to use.

auth_db

VdkCString   Deprecated; do not use.

charSetName

VdkCString   Character set used internally by VDK.



Returns

This function must return one of the following error codes:

VdkSuccess for success

 

VdkError_* for a standard Verity Developer Kit API error as described in the Verity Developer’s Kit Programming Reference

 

VdkFail for a non-specific error

 


Discussion

Your VgwSessionNewFnc function should store the information it will need on a per-session basis in a callback argument handle and assign the handle to pvgwSession. This handle represents the session’s context. For example, the session context may include the collection or document source information associated with the session.

The handle points to a _VgwAppSession structure that your gateway driver must define. You should call VdkStructInit on the handle before assigning values to it; this action guarantees that optional or empty fields in the structure are set to NULL.

Other kinds of initialization that can occur in your VgwSessionNewFnc function can include:

Opening or setting up the data source associated with the gateway or initializing the data source’s software for read access.

 

Setting up character sets.

 

Reading style configuration files; for example, the gateway-supplied configuration file. For more information about this file, see Gateway Configuration File.

 

If execution of your VgwSessionNewFnc function results in an error, you are responsible for freeing any resources used by the objects that you have created before returning from this function.


Example

typedef struct _VgwAppSession
{
VdkCBArg drvAppData; /* driver handle returned by
VdkDrvNewCBFnc */
VdkSession vdkSession; /* the VDK session handle */
VdkCollection collection; /* the VDK collection handle */
VdkDocSource docSource; /* the VDK docsource handle */
VdkCString configDirectory; /* style directory of gateway
config files */
VdkUint2 securityModuleId; /* security id for session */

} VgwAppSessionRec;

static VdkError
VDK_CALLBACK VgwSessionNew(VgwSessionNewArg pNewArg,
VgwAppSession* ppSession)
{
VgwAppSession pVSes = NULL;

if (!ppSession)
return VdkError_InvalidArgs;
*ppSession = NULL;

if (!pNewArg)
return VdkError_InvalidArgs;

if( !(pVSes =
(VgwAppSession)malloc(sizeof(VgwAppSessionRec))) )
return VdkError_OutOfMemory;

/*********************************************
* save session related objects for later use
*********************************************/

memset(pVSes, 0, sizeof(VgwAppSessionRec));

pVSes->drvAppData = pNewArg->drvAppData;
pVSes->vdkSession = pNewArg->vdkSession;
pVSes->collection = pNewArg->collection;
pVSes->docSource = pNewArg->docSource;
pVSes->configDirectory =
(VdkCString)strdup((const char*)pNewArg->configDirectory);
pVSes->securityModuleId = pNewArg->securityModuleId;
if (!pVSes->securityModuleId)
pVSes->securityModuleId = GdkGetSecurityId(pGdkHandle);

*ppSession = pVSes;
return VdkSuccess;
}