VgwDocExistFnc


Use the VgwDocExistFnc function to specify whether the specified document exists and the user should be allowed access to it. The Verity engine calls your VgwDocExistFnc function in response to a request by an application, which typically occurs when a user attempts to view a document.


Syntax

VdkError VgwDocExistFnc(
   VgwAppSession    vgwSession,
   VdkUser          vdkUser,
   VgwDocExistArg   pExistArg)

Arguments

 


vgwSession

VgwAppSession   The session handle that contains session-related data, which was set in your driver’s VgwSessionNewFnc function.

vdkUser

VdkUser   A handle that identifies the user requesting access to the document.

pExistArg

VgwDocExistArg   A handle to a VgwDocExistArg structure that identifies the document for which access must be determined. On return, this structure will identify whether or not access is allowed.


Member Descriptions

 

Table 6-8    VgwDocExistArg Members


Member

Type/Description

docKey

VdkDocKey   External key of the document to be checked.

docSet

VdkDocSet   A VDK docset handle that specifies a key that can be used to retrieve field information for the document.

flags

VdkUint4   Reserved for future use.



Returns

This function must return one of the following error codes:

VdkSuccess for success, meaning that the specified document exists and the user should be allowed access to it

 

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 VgwDocExistFnc function must return VdkSuccess if the document exists and access to it is allowed. An efficient implementation of this function is especially important in situations in which large numbers of invalid keys exist as this function could be called many times.

Your VgwDocExistFnc function can implement any scheme to check access rights. You can compare access information in the repository against any criteria; for example, you can check any of the following items against the document’s access information:

data in a certificate associated with the user, such as the “group”

 

the kind of certificate, such as an administrator’s certificate

 

the certificate’s state, such as whether or not the certificate is valid

 

specific values in an access control list, such as a constant assigned to specific users or groups

 

Multiple criteria can be used.

If you need field information from the collection, you can use the docSet member to identify the document; for example, you can use the docSet member in calls to VdkDocSetRead to obtain a file name (DOC_FN field) or URL (URL field).

Your driver’s session handle can specify whether or not to use security. For more information, see the example under VgwSessionNewFnc in Session Interface. If NULL is specified for a security module, security is not enabled for your repository; in which case, you should always return VdkSuccess.

Your VgwDocExistFnc function is responsible for releasing memory and other resources before returning.

In addition to the Verity engine calling your VgwDocExistFnc function, you can call VgwDocExistFnc also; for example, you can call VgwDocExistFnc or an optimized version of it from your gateway driver’s VgwStreamNew and VgwDocFieldRead callback functions to check whether the document exists and access is allowed before setting up a stream or reading fields.


Example

static VdkError
VDK_CALLBACK VgwDocExist(VgwAppSession pSession,
VdkUser pUser, VgwDocExistArg pExistArg)
{
VdkError error = VdkSuccess;
VSecCertificate pCert = NULL;
VdkUserFindArgRec arg;

if (!pSession || !pExistArg)
return VdkError_InvalidArgs;

if( !pExistArg->docKey ||
!strlen((const char*)pExistArg->docKey) )
return VdkError_InvalidDoc;

/***************************************************************
* with no security module, all documents are considered public
***************************************************************/

if (!pSession->securityModuleId)
return VdkSuccess;

/**********************************************************
* check access based on whether document is public or not
**********************************************************/

if (!pUser)

/**********************************
* assume all documents are secure
**********************************/

return VdkError_InvalidUser;

/*******************************************************
* assumes all documents come from one repository 'abc'
*******************************************************/

VdkStructInit(&arg);
arg.secId = pSession->securityModuleId;
arg.repId = (VdkUint4)VGWR_ONEID;

/***************************************************************
* check all matching VDK certificates in the VdkUser object
* for possible access to the document that VdkDocKey specifies
***************************************************************/

while (VdkSuccess == (error =
VdkUserFindCertificate(pUser, &arg, &pCert))) {

/******************************************************
* check access based on user's VDK certificate object
* and document's VdkVgwKey field value
******************************************************/

if (!pCert)
continue;

/***********************************************
* check stored made up uid in prData and
* give only 'abc' user access to all documents
***********************************************/
#define USERUID ('a'+'b'+'c')

if( (pCert->prState & TicketInvalid) ||
!(pCert->prState & TicketValid) )
continue;

if (!pCert->prData)
continue;
else if (pCert->prData == (VdkVoidp)USERUID)
break;
}

if (VdkError_HandleNotFound == error)
error = VdkError_Access;
return error;
}