VgwStreamNewFnc


Use the VgwStreamNewFnc function to create a stream for access to the contents of a document. The Verity engine calls your VgwStreamNewFnc function when a collection is opened or a document source is created.


Syntax

VdkError VgwStreamNewFnc(
   VgwAppSession     vgwSession,
   VdkUser           vdkUser,
   VgwStreamNewArg   vgwStreamNewArg,
   VgwAppStream*     pvgwStream)

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.

vgwStreamNewArg

VgwStreamNewArg   A pointer to a populated VgwStreamNewArgRec structure.

pvgwStream

VgwAppStream*   A pointer to a VgwAppStream structure, which specifies information about the stream.


Member Descriptions

 

Table 7-1    VgwStreamNewArgRec Members


Member

Type/Description

vdkSession

VdkSession   A VDK session handle.

collection

VdkCollection   A VDK collection handle.

docSource

VdkDocSource   A VDK document source handle.

docStream

VdkDocStream   A VDK document stream handle.

strAppData

VdkVoidp   A pointer to application-specific data passed by VdkDocStreamNew, which is described in the Verity Developer’s Kit Programming Reference.

field

VdkCString   The field name that specifies the initial field to receive the stream’s content. If the value is “DOC” or NULL, the stream should return the contents of the primary document; otherwise, the stream should return the contents of the specified field, which was set in style.dft.

key

VdkDocKey   The current document’s key.

flags

VdkUint4   Behavior flags, which are ORed together to specify the kind of operation. Valid values are:

VgwAccessMode_Index for indexing or viewing (the value of this bit is 1 if indexing or 0 if viewing)

VgwAccessMode_Head for HTTP head request

VgwAccessMode_Seek to seek

VgwAccessMode_FName to accept FileByName

dispatchFN

VdkCString   Name of the content, such as a filename.

dispatchOF

VdkInt4   Offset into the content to start.

dispatchSZ

VdkInt4   Size, in bytes, of the content.

docSet

VdkDocSet   Reserved for future use.

docSetRow

VdkUint4   Reserved for future use.

bufSize

VdkUint4   The desired size of the buffer token.



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

Your VgwStreamNewFnc function must populate a VgwAppStream structure, which the Verity engine passes to your driver’s VgwStreamGetTokenFnc callback function.

Your VgwStreamNewFnc function should store the information it will need on a per-stream basis in the VgwAppStream handle and assign the handle to pvgwStream. This handle represents the streams’s context. For example, the stream context may include the buffer size and token count.

The handle points to a _VgwAppStream 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.

Your VgwStreamNewFnc function can set up the data source associated with the stream; for example, by loading an entire document into memory.

If execution of your VgwGetSchemaFnc 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.


Example

typedef struct _VgwAppStream
{
VgwAppSession pSession;
VdkUser pUser;

VdkVoidp strAppData; /* appData from VdkDocStreamNew */
VdkUint4 flags; /* VgwAccessMode_* flags */
VdkDocKey key; /* current document key */
VdkCString field; /* text blob field name */
VdkUint4 bufSize; /* desired size of buffer token */

VdkUint4 lastToken;

} VgwAppStreamRec;

static VdkError
VDK_CALLBACK VgwStreamNew(VgwAppSession pSession,
VdkUser pUser,
VgwStreamNewArg pNewArg,
VgwAppStream *ppStream)
{
VdkError error = VdkSuccess;
VgwAppStream pVStrm = NULL;
VgwDocExistArgRec arg;

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

if (!pNewArg)
return VdkError_InvalidArgs;

/**************************************************
* honor document level security whenever possible
**************************************************/

VdkStructInit(&arg);
arg.docKey = pNewArg->key;
if (VdkSuccess != (error = VgwDocExist(pSession, pUser, &arg)))
return error;

if( !(pVStrm =
(VgwAppStream)malloc(sizeof(VgwAppStreamRec))) )
return VdkError_OutOfMemory;

/**********************************************************
* save the document info for later token stream operation
**********************************************************/

memset(pVStrm, 0, sizeof(VgwAppStreamRec));

pVStrm->pSession = pSession;
pVStrm->pUser = pUser;
pVStrm->strAppData = pNewArg->strAppData;
pVStrm->flags = pNewArg->flags;

if( !(pVStrm->key =
(VdkDocKey)strdup((const char*)pNewArg->key)) ){

free(pVStrm);
return VdkError_OutOfMemory;
}

if( !(pVStrm->field =
(VdkCString)strdup((const char*)pNewArg->field)) ){

free((void*)pVStrm->key);
free(pVStrm);
return VdkError_OutOfMemory;
}

pVStrm->bufSize = pNewArg->bufSize;
pVStrm->lastToken = 0;

*ppStream = pVStrm;
return VdkSuccess;
}