VgwSessionGetInfoFnc


Use the VgwSessionGetInfoFnc function to return configuration and status information for a session. The Verity engine calls your VgwSessionGetInfoFnc function when it needs information about the session.


Syntax

VdkError VgwSessionGetInfoFnc(
   VgwAppSession        vgwSession,
   VgwSessionInfoOut*   pvgwSessionInfoOut)

Arguments

 


vgwSession

VgwAppSession   A reference to the handle created in your VgwSessionNewFnc callback function.

pvgwSessionInfoOut

VgwSessionInfoOut*   A pointer to an information packet handle that contains information about the session.


Member Descriptions

 

Table 3-2    VgwSessionInfoOutRec Members


Member

Type/Description

name

VdkCString   The short name of the gateway driver.

majorRev

VdkUint2   The major revision of the gateway driver.

minorRev

VdkUint2   The minor revision of the gateway driver.

infoCount

VdkUint2   The number of string elements in infoArray.

infoArray

VdkCString*   An array of strings that contain textual information about session; for example, the product name of the associated repository, version, copyright message information, and attribution to third party vendors and products.

count

VdkInt4   The number of active instances of the gateway driver.

sessAppData

VdkVoidp   A reference to the handle created in your VgwSessionNewFnc callback function.

drvAppData

VdkCBArg   The driver handle that contains your driver’s global data, which was set by 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   The style directory that contains the gateway configuration files.

configuration

VdkCString   The configuration specification whose value was obtained from the configuration statement in the collection's style.vgw file.

configCount

VdkInt2   The number of gateway driver configuration pair elements in configNameArray and configValueArray arrays.

configNameArray

VdkCString*   An array of gateway configuration specification names for the gateway driver.

configValueArray

VdkCString*   An array of gateway configuration specification values for the gateway driver.

methods

_VdkSessionGatewayArg*   Internal; do not use.

securityCapabilities

VdkInt4   Bitmask of authentication and ACLs provided by the gateway.

securityModelMask

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

repositoryCount

VdkUint2   The number of VDK repositories accessed by the gateway driver.

repositoryArray

VdkRepository*   An array of VDK repositories accessed by the gateway driver.

dataSourceCount

VdkUint2   Deprecated; do not use.

dataSources

_VdkDocSource**   Deprecated; do not use.

protocols

ProtocolList*   Deprecated; do not use.

ancillaryCount

VdkUint2   Deprecated; do not use.

ancillaryInfos

_VgwSessionInfoOut**   Deprecated; do not use.

gdkRev

VdkUint4   The GDK version compliance information for the gateway driver.



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

The VgwSessionGetInfoFnc function maps the information stored in your driver’s session handle to field names understood by the Verity engine. Most of the information returned by this function is passed into the function directly or indirectly via the session handle, although constant information can be returned by this structure as well.

The information returned by VgwSessionGetInfo is immutable by the calling application and by the Verity engine. You can create a single per-session version of the information, which is returned for each request.

You should call VdkStructInit on the returned information structure, pvgwSessionInfoOut, before assigning values to it; this action guarantees that optional or empty fields are set to NULL.

Your VgwSessionGetInfoFnc function sets up an array of _VdkRepository structures, which are specified by the vdkRepository member of the VgwSessionInfoOutRec structure. (VdkRepository is a pointer to a _VdkRepository structure.) Each _VdkRepository structure identifies a repository or part of a repository, such as folders in a file-system gateway or domains determined by a regular expression in an HTTP gateway. The following table identifies the members of a _VdkRepository structure:

 

Table 3-3    _VdkRepositoryRec Members


Member

Type/Description

repository_type_name

VdkCString   Repository protocol or type.

repository_name

VdkCString   Repository name or combination of hostname and repository name.

security_module_id

VdkUint2   The ID of the security module to perform authentication for this repository.

repository_id

VdkUint4   The repository ID.

appData

VdkVoidp   Reserved for future use.

appDataSz

VdkUint4   Reserved for future use.

repos_flags

VdkUint4   Reserved for future use.


You specify your own repository name and ID; for example, the repository name could be a table name in a database and the ID could be a value created by hashing the table name. The security module ID should be the same ID that is passed to your VgwSessionNewFnc function in the securityModuleId member of the VgwSessionNewArgRec structure. For more information on the repository protocol, see Creating Document Keys.


Example

/***********************************************
* define gw driver description properties here
***********************************************/
/*
#define VGW_NAME "Verity GDK Sample Gateway"*/
#define VGW_MAJORVER 2
#define VGW_MINORVER 0
#define VGW_REPTYPE_NAME "GDK Sample"

#define VGWR_ONE (VdkCString)"abc"
#define VGWR_ONEID 'a'+'b'+'c'

static VdkError
VDK_CALLBACK VgwSessionGetInfo(VgwAppSession pSession,
VgwSessionInfoOut *ppInfo)
{
static VdkCString vgw_infoArray[] = {
(VdkCString)"Verity GDK Sample Gateway, to be used as a template",
(VdkCString)"Copyright (C) 2001 Verity Inc."
};
VgwSessionInfoOut pInfo = NULL;

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

if (!pSession)
return VdkError_InvalidArgs;

if( !(pInfo = malloc(sizeof(VgwSessionInfoOutRec))) )
return VdkError_OutOfMemory;

VdkStructInit(pInfo);

/******************************************************
* provide gateway driver description information here
******************************************************/

pInfo->name = (VdkCString)VGW_NAME;
pInfo->majorRev = (VdkUint2)VGW_MAJORVER;
pInfo->minorRev = (VdkUint2)VGW_MINORVER;
pInfo->infoCount = (VdkUint2)sizeof(vgw_infoArray)/ sizeof(vgw_infoArray[0]);
pInfo->infoArray = vgw_infoArray;

/****************************************************
* provide gateway session stored information that
* can be used to locate the VDK kernel context here
****************************************************/

pInfo->drvAppData = pSession->drvAppData;
pInfo->vdkSession = pSession->vdkSession;
pInfo->collection = pSession->collection;
pInfo->docSource = pSession->docSource;
pInfo->configDirectory = pSession->configDirectory;

/****************************************************
* provide gateway repository array information here
****************************************************/
{
VdkUint2 n = pInfo->repositoryCount = 1;
if( !(pInfo->repositoryArray = malloc(sizeof(VdkRepository)*n+1)) ){
free(pInfo);
return VdkError_OutOfMemory;
}

for( ; (n-- > 0); ){
if( !(pInfo->repositoryArray[n] =
        malloc(sizeof(VdkRepositoryRec))) ){
while (++n < pInfo->repositoryCount) {
if (!pInfo->repositoryArray[n])
continue;

free(pInfo->repositoryArray[n]);
pInfo->repositoryArray[n] = NULL;
}
free(pInfo->repositoryArray);
free(pInfo);
return VdkError_OutOfMemory;
}

/*************************************************
* assign the sample gateway repository type name
*************************************************/

pInfo->repositoryArray[n]->repository_type_name =
(VdkCString)VGW_REPTYPE_NAME;

/ **************************************************************
* assign the repository name and id, which should be
* consistent and valid across collections and docsources for
* documents that come from the same gateway repository source
**************************************************************/

pInfo->repositoryArray[n]->repository_name = (VdkCString)VGWR_ONE;
pInfo->repositoryArray[n]->repository_id = (VdkUint4)VGWR_ONEID;

/ ************************************************************
* assign the repository security module id, which should be
* consistent and valid across collections and docsources
* zero means a public vdk repository
************************************************************/

pInfo->repositoryArray[n]->security_module_id =
pSession->securityModuleId;
}
}

/**************************************************
* provide GDK version compliance information here
**************************************************/

pInfo->gdkRev = (VdkUint4)GDK_RELEASE;

*ppInfo = pInfo;
return VdkSuccess;
}