VdkDrvNewCBFnc


Use the VdkDrvNewCBFnc function to create a context for your gateway driver; for example, by saving parameters for use by your driver’s callback functions. The Verity engine calls your VdkDrvNewCBFnc function immediately after the gateway driver is loaded into memory and the driver’s attributes array has been successfully parsed. It is called once per instance of a driver.


Syntax

VdkError VdkDrvNewCBFnc(
   VdkCBArg*     pdriverHandle,
   VdkInt2       argc,
   VdkCString*   argv,
   VdkVoidp*     vdkAttrs)

Arguments

 


pdriverHandle

VdkCBArg*   A handle to data available to your driver’s callback functions.

argc

VdkInt2   The number of elements in argv.

argv

VdkCString*   The arguments passed to the driver via the connection specification, connspec; argv[0] is the driver name, argv[1] is the first argument in the connection specification, and so on.

vdkAttrs

VdkVoidp*   A NULL-terminated array of name-value pairs constructed as an array of VdkVoidp elements, name first, value second.


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 VdkDrvNewCBFnc callback function has access to the arguments specified in the connection specification (see DDA Specification File) via argv, as well as arguments passed to it from the Verity engine in the vdkAttrs array, which are identified in the following table:

 


Attribute

Type/Description

VdkDrvNew_Gsv

VdkVoidp   Verity engine thread global storage area. Do not use or modify.

VdkDrvNew_ErrFunc

VdkDrvErrorCBFnc   Verity-provided error and/or status message output callback function.

VdkDrvNew_ErrArg

VdkCBArg   Message callback handle.

VdkDrvNew_YieldFunc

VdkDrvYieldCBFnc   Verity-provided yield callback function.

VdkDrvNew_YieldArg

VdkCBArg   Yield callback handle.

VdkDrvNew_Info

VdkVoidp*   A pointer to the driver instance information handle.

VdkDrvNew_VdkHome

VdkCString   The pathname of the VDK home directory; typically, the home directory is the common directory of the directory in which you installed K2 Developer.

VdkDrvNew_VdkVersion

VdkUint4   A pointer to a string that specifies the VDK version.


Your VdkDrvNewCBFnc function should store the arguments it will need, along with other information that you wish to keep on a per-driver basis, in a callback argument handle and assign the handle to pdriverHandle. This handle represents the driver’s context.

You should initialize per-driver objects in this function. You may need to maintain a reference count to handle the allocation and release of memory for global objects defined in this function.

To implement security, your VdkDrvNewCBFnc function should obtain a handle to the GDK library. For more information about the GDK library, see Gateway Developer Kit Library.

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

#define VGW_NAME "Verity GDK Sample Gateway"
typedef struct _VdkDrvObjs
{
VdkVoidp gsv; /* VDK global storage area */
VdkDrvErrorCBFnc ErrorCB; /* message callback function */
VdkCBArg ErrorArg; /* args for callback handle */

} VdkDrvObjsRec, *VdkDrvObjs;

static VdkError
VDK_CALLBACK VdkDrvNew(VdkCBArg* pdrvHandle, VdkInt2 argc,
VdkCString* argv, VdkVoidp* vdkAttrs)
{
VdkError error = VdkSuccess;
VdkDrvObjs pDrvObjs;
assert(pdrvHandle);
*pdrvHandle = NULL;

if( !(pDrvObjs =
(VdkDrvObjs)malloc(sizeof(VdkDrvObjsRec))) )
return VdkError_OutOfMemory;

memset(pDrvObjs, 0, sizeof(VdkDrvObjsRec));
assert(vdkAttrs);

/************************************************
* save the error callback function into appData
************************************************/

for( ; *vdkAttrs; vdkAttrs += 2 ) {
if (!strcmp((const char*)VdkDrvNew_Gsv,
(const char*)vdkAttrs[0]))
pDrvObjs->gsv = vdkAttrs[1];
else if (!strcmp((const char*)VdkDrvNew_ErrFunc,
(const char*)vdkAttrs[0]))
pDrvObjs->ErrorCB = (VdkDrvErrorCBFnc)vdkAttrs[1];
else if (!strcmp((const char*)VdkDrvNew_ErrArg,
(const char*)vdkAttrs[0]))
pDrvObjs->ErrorArg = (VdkCBArg)vdkAttrs[1];
}

if (!nDrvCnt++) {
GdkHandleNewArgRec arg;

/*********************************************************
* create global gdk library handle needed to implement
* security and access gdk library support functions here
*********************************************************/

GdkStructInit(&arg);
arg.name = (VdkCString)VGW_NAME;
arg.vdkAttrs = vdkAttrs;

/ ***************************************************************
* retrieve the pointer to the gateway methods attributes table
***************************************************************/

if (VdkSuccess != (error = vgwsamp((VdkVoidp*)&arg.gwAttrs))) {
VdkDrvFree(pDrvObjs);
return error;
}

if (VdkSuccess != (error = GdkHandleNew(&arg, &pGdkHandle))) {
VdkDrvFree(pDrvObjs);
return error;
}
}

*pdrvHandle = pDrvObjs;
return error;
}