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.


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




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


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


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




VdkDocKey   External key of the document to be checked.


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


VdkUint4   Reserved for future use.


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



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.


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'

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)

* 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) )

if (!pCert->prData)
else if (pCert->prData == (VdkVoidp)USERUID)

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