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.


VdkError VgwSessionNewFnc(
   VgwSessionNewArg   vgwSessionNewArg,
   VgwAppSession*     pvgwSession)




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


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




VdkVoidp   Gateway-defined data.


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


VdkSession   The VDK session handle.


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


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


VdkCString   A style directory that contains the gateway configuration files.


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


AppCBList*   Deprecated; do not use.


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


VdkUint2   Security model for this session to use.


VdkCString   Deprecated; do not use.


VdkCString   Character set used internally by VDK.


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



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.


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;