VgwDocSetNewFnc


Use the VgwDocSetNewFnc function to create a context for a document set and to perform other initialization. The Verity engine calls your VgwDocSetNewFnc function when it traverses folder or document keys.


Syntax

VdkError VgwDocSetNewFnc (
   VgwAppSession vgwSession,
   VdkUser vdkUser,
   VgwDocSetNewArg vgwDocSetNewArg,
   VgwDocSet* pvgwDocSet)

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 this repository.

vgwDocSetNewArg

VgwSessionNewArg A reference to a VgwDocSetNewArgRec structure, which is provided as input to the gateway from the crawling application.

pvgwDocSet

VgwDocSet* A pointer to a gateway’s document set handle which, on success, will be set by this function.


Member Descriptions

 

Table 8-1    VgwDocSetNewArgRec Members


Member

Type/Description

maxColumnSize

VdkUint2 The maximum size of an entry.

columnCount

VdkUint2 The number of names in columnArray.

columnArray

VdkCString* The list of field names.

flags

VdkUint4 Any of the following values, some of which can be ORed together:

VgwDocSet_ShowLeaves - return leaf entries

VgwDocSet_ShowFolders - return folder entries

VgwDocSet_AbsolutePath - return absolute path entries (Reserved for future use)

VgwDocSet_Update - return changed entries (can be ORed)

reposId

VdkUint2 Reserved for future use.

startPoint

VdkCString The starting location for navigation.

depth

VdkInt4 Reserved for future use.

startDate

VdkDate The last modified date range start date for returned entries.

stopDate

VdkDate Reserved for future use.

query

VdkCString A spider argument passed down “as is” to all gateways.

docSet

VdkDocSet Reserved for future use.

idCount

VdkUint4 Reserved for future use.

idArray

VdkDocId* Reserved for future use.

outServerDate

VdkDate Reserved for future use.

outFlags

VdkUint4 Reserved for future use.



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

 


Discussion

The VgwDocSetNewFnc function sets up reading of a document set from a repository. Your VgwDocSetNewFnc function creates a private VgwDocSet object that provides context for VgwDocSetReadFnc calls.

You can either provide access to the folders in a document set or actual documents in the document set, but not both folders and documents in the same document set. To specify folders the calling application sets the flags member of the VgwDocSetNewArgRec structure to VgwDocSet_ShowFolders. To specify documents, the calling application sets the flags member of the VgwDocSetNewArgRec structure to VgwDocSet_ShowLeaves.

You must call the VdkStructInit function to initialize the VgwDocSetNewArgRec structure before you can use it.

You can use the query member of the VgwDocSetNewArgRec structure to customize the operation of the VgwDocSetReadFnc function; this member becomes available to all gateways and all collections, regardless of the starting point folder. It is a global per-process input parameter.

You can define a member in your VgwDocSet structure to store the startDate member of the VgwDocSetNewArgRec structure and use this date with the last modified date of a folder or document to determine whether it needs to be updated by a crawling application. Folders are crawled when the flags member of the VgwDocSetNewArgRec structure is set to VgwDocSet_ShowFolders. Documents are crawled when the flags member is set to VgwDocSet_ShowLeaves.


Example

typedef struct _VgwKeyInfo
{
VdkCString vdkkey;
VdkCString parent;
VdkDate date;
VdkBool isFolder;

} VgwKeyInfoRec;

typedef struct _VgwKeyInfo* VgwKeyInfo;

typedef struct _VgwDocSet
{
VgwAppSession pSession; /* Vgw Session handle */
VdkUser pUser; /* Vdk User handle */

VdkUint2 maxColumnSize; /* Max size of an entry */
VdkUint2 columnCount; /* Num of names in columnArray */
VgwColumnInfo* columnArray;   /* Column info for field values */

VdkUint4 flags;     /* VgwDocSet_* flags OR'ed together */
VdkCString startPoint; /* Starting loc. for navigation */
VdkDate startDate;   /* Last modified range start date */

VgwKeyInfo queue;         /* key queue */
VdkUint4 keycount; /* total count of keys in queue */

} VgwDocSetRec;

#define DOCSETCOUNT 3

static VgwKeyInfoRec docsetEntries[] =
{
{(VdkCString)"samp://folder1", NULL,
0xffffffff, True},
{(VdkCString)"samp://folder1/doca",(VdkCString)"samp://folder1",
0xffffffff, False},
{(VdkCString)"samp://folder1/docb",(VdkCString)"samp://folder1",
0xffffffff, False}
};

#define FIELDCOUNT 6
#define FIXEDACL "294"

#define VGWF_SECFLAG (VdkCString)"_VgwAccessType"
#define VGWF_ACLCACHE (VdkCString)"_VgwAccessValue"
#define VGWF_DOCFLD (VdkCString)"DOC"
#define VGWF_DOCKEY (VdkCString)"VgwDocKey"
#define VGWF_VWURL (VdkCString)"VgwViewURL"

static VgwColumnInfoRec reposColInfo[] =
{
{VdkFieldType_Invalid, (VdkCString)"", 0,
VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Text, (VdkCString)VDK_VGWKEY, 0,
VgwColumn_PrimaryKey | VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Unsigned, VGWF_SECFLAG, 0,
VgwColumn_ReadOnly | VgwColumn_InLine, 0, 0},
{VdkFieldType_Text, VGWF_ACLCACHE, 0,
VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Stream, VGWF_DOCFLD, 0,
VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Text, VGWF_DOCKEY, 0,
VgwColumn_PrimaryKey | VgwColumn_ReadOnly, 0, 0},
{VdkFieldType_Text, VGWF_VWURL, 0,
VgwColumn_RedirectURL | VgwColumn_ReadOnly, 0, 0}
};

static VdkError
VDK_CALLBACK VgwDocSetNew(VgwAppSession pVSes, VdkUser pUsr,
VgwDocSetNewArg pNewArg, VgwDocSet* ppVDSet)
{
VdkError error = VdkFail;
VdkBool bFound;
VdkUint4 i;
VdkUint2 j, k;
  VgwDocSet pVDSet = NULL;
VgwColumnInfo pInfos;

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

if( !pVSes || !pNewArg )
return VdkError_InvalidArgs;

/ *****************************************************************
* gateway returns VdkError_InvalidArgs if both
* VgwDocSet_ShowLeaves and VgwDocSet_ShowFolders flags are not set
*****************************************************************/

if( !(pNewArg->flags & VgwDocSet_ShowLeaves) &&
!(pNewArg->flags & VgwDocSet_ShowFolders) )
return VdkError_InvalidArgs;

if( !(pVDSet = (VgwDocSet)malloc(sizeof(VgwDocSetRec))) )
return VdkError_OutOfMemory;

/**************************************
* save the docset input for use later
**************************************/

pVDSet->pSession = pVSes;
pVDSet->pUser = pUsr;

pVDSet->maxColumnSize = pNewArg->maxColumnSize;
pVDSet->columnCount = pNewArg->columnCount;

if( !(pVDSet->columnArray = (VgwColumnInfo*)
malloc(sizeof(VgwColumnInfo)*(pVDSet->columnCount+1))) ){
free(pVDSet);
return VdkError_OutOfMemory;
}

if( !(pInfos = (VgwColumnInfo)
malloc(sizeof(VgwColumnInfoRec)*(pVDSet->columnCount+1))) ){
free(pVDSet->columnArray);
free(pVDSet);
return VdkError_OutOfMemory;
}

if (pNewArg->columnArray) {
for( j = 0; j < pVDSet->columnCount; j++ ){
pVDSet->columnArray[j] = &pInfos[j];

/*******************************
* use static field column info
*******************************/

for( k = 1; k <= FIELDCOUNT; k++ ){
if (stricmp((const char*)reposColInfo[k].name,
(const char*)pNewArg->columnArray[j]))
continue;

*pVDSet->columnArray[j] = reposColInfo[k];
}

if (k > FIELDCOUNT)
*pVDSet->columnArray[j] = reposColInfo[0];
}

} else {

/*********************************************************
* gateway should populate at least one column VdkVgwKey,
* if calling app does not ask for any columns
*********************************************************/

pVDSet->columnCount = 1;
pVDSet->columnArray[0] = &pInfos[0];

*pVDSet->columnArray[0] = reposColInfo[1];
}

pVDSet->flags = pNewArg->flags;

if( pNewArg->startPoint && !(pVDSet->startPoint =
(VdkCString)malloc(strlen(
      (const char*)pNewArg->startPoint)+1)) ){
free(pVDSet->columnArray[0]);
free(pVDSet->columnArray);
free(pVDSet);
return VdkError_OutOfMemory;
}
strcpy((char*)pVDSet->startPoint,
          (const char*)pNewArg->startPoint);

pVDSet->startDate = pNewArg->startDate;

/********************************************************
* sample gateway hard-codes a folder1 entry with 2 leaf
* documents doca and docb stored in docsetEntries
********************************************************/

if( !(pVDSet->queue = (VgwKeyInfo)
malloc(sizeof(VgwKeyInfoRec)*DOCSETCOUNT)) ){
free((void*)pVDSet->startPoint);
free(pVDSet->columnArray[0]);
free(pVDSet->columnArray);
free(pVDSet);
return VdkError_OutOfMemory;
}

/***************************************************
* sample gateway applies filter models here
* sample gateway supports Model 1 using startPoint
***************************************************/

for( i=0, j=0; i < DOCSETCOUNT; i++ ){

/***********************************************
* sample gateway honors folder and leaves flag
***********************************************/

if( (pVDSet->flags & VgwDocSet_ShowLeaves) &&
!docsetEntries[i].isFolder )
bFound = True;

else if( (pVDSet->flags & VgwDocSet_ShowFolders) &&
docsetEntries[i].isFolder )
bFound = True;

else
bFound = False;

if (!bFound)
continue;

/****************************************************
* sample gateway honors startpoint for folders only
****************************************************/

bFound = False;

if (!docsetEntries[i].parent) {
if (!pVDSet->startPoint)
bFound = True;

} else {

/********************************
* looking for parent entry here
********************************/

for( k=0; k < DOCSETCOUNT; k++ ){
if (!stricmp(docsetEntries[k].vdkkey,
                     docsetEntries[i].parent))
break;
}
assert(k < DOCSETCOUNT);
if (!stricmp(pVDSet->startPoint, docsetEntries[k].vdkkey))
bFound = True;
}

if (!bFound)
continue;

/ ***************************************************************
 * gateway should always filter when startDate is supplied
 * sample gateway honors update flags and/or startDate settings
***************************************************************/

if( pVDSet->startDate || (pVDSet->flags & VgwDocSet_Update) ){

/ *************************************************************
 * sample gateway hardcodes date, so startdate is always less
*************************************************************/
if (!pVDSet->startDate)
bFound = True;
else if (pVDSet->startDate <= docsetEntries[i].date)
bFound = True;
else
bFound = False;

if (!bFound)
continue;
}

/***************************************************
* honor document level security whenever possible,
* consider performance and scalability trade offs
***************************************************/
{
VgwDocExistArgRec arg;

VdkStructInit(&arg);
arg.docKey = docsetEntries[i].vdkkey;
if (VdkError_Access == (error =
VgwDocExist(pVDSet->pSession, pVDSet->pUser, &arg)))
continue;

else if (VdkSuccess != error) {
free(pVDSet->queue);
free((void*)pVDSet->startPoint);
free(pVDSet->columnArray[0]);
free(pVDSet->columnArray);
free(pVDSet);
return error;
}
}

/********************
* save docset entry
********************/

StructAssign(&pVDSet->queue[j], &docsetEntries[i]);
j++;
}

pVDSet->keycount = j;
*ppVDSet = pVDSet;

return VdkSuccess;
}