VDSF
Menu
You are here: Home

API functions for vdsf sessions.


Functions

VDSF_EXPORT int vdsCommit (VDS_HANDLE sessionHandle)
 Commit all insertions and deletions (of the current session) executed since the previous call to vdsCommit or vdsRollback.
VDSF_EXPORT int vdsCreateObject (VDS_HANDLE sessionHandle, const char *objectName, size_t nameLengthInBytes, vdsObjectType objectType)
 Create a new object in shared memory.
VDSF_EXPORT int vdsDestroyObject (VDS_HANDLE sessionHandle, const char *objectName, size_t nameLengthInBytes)
 Destroy an existing object in shared memory.
VDSF_EXPORT int vdsErrorMsg (VDS_HANDLE sessionHandle, char *message, size_t msgLengthInBytes)
 Return the error message associated with the last error(s).
VDSF_EXPORT int vdsExitSession (VDS_HANDLE sessionHandle)
 Terminate the current session.
VDSF_EXPORT int vdsGetInfo (VDS_HANDLE sessionHandle, vdsInfo *pInfo)
 Return information on the current status of the VDS (Virtual Data Space).
VDSF_EXPORT int vdsGetStatus (VDS_HANDLE sessionHandle, const char *objectName, size_t nameLengthInBytes, vdsObjStatus *pStatus)
 Return the status of the named object.
VDSF_EXPORT int vdsInitSession (VDS_HANDLE *sessionHandle)
 This function initializes a session.
VDSF_EXPORT int vdsLastError (VDS_HANDLE sessionHandle)
 Return the last error seen in previous calls (of the current session).
VDSF_EXPORT int vdsRollback (VDS_HANDLE sessionHandle)
 Rollback all insertions and deletions (of the current session) executed since the previous call to vdsCommit or vdsRollback.

Function Documentation

VDSF_EXPORT int vdsCommit ( VDS_HANDLE  sessionHandle  ) 

Commit all insertions and deletions (of the current session) executed since the previous call to vdsCommit or vdsRollback.

Insertions and deletions subjected to this call include both data items inserted and deleted from data containers (maps, etc.) and objects themselves created with vdsCreateObj and/or destroyed with vdsDestroyObj.

Note: the internal calls executed by the engine to satisfy this request cannot fail. As such, you cannot find yourself with an ugly situation where some operations were committed and others not. If an error is returned by this function, nothing was committed.

Parameters:
[in] sessionHandle Handle to the current session.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsCreateObject ( VDS_HANDLE  sessionHandle,
const char *  objectName,
size_t  nameLengthInBytes,
vdsObjectType  objectType 
)

Create a new object in shared memory.

The creation of the object only becomes permanent after a call to vdsCommit.

This function does not provide a handle to the newly created object. Use vdsQueueOpen and similar functions to get the handle.

Parameters:
[in] sessionHandle Handle to the current session.
[in] objectName The fully qualified name of the object.
[in] nameLengthInBytes The length of objectName (in bytes) not counting the null terminator (null-terminators are not used by the vdsf engine).
[in] objectType The type of object to create (folder, queue, etc.).
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsDestroyObject ( VDS_HANDLE  sessionHandle,
const char *  objectName,
size_t  nameLengthInBytes 
)

Destroy an existing object in shared memory.

The destruction of the object only becomes permanent after a call to vdsCommit.

Parameters:
[in] sessionHandle Handle to the current session.
[in] objectName The fully qualified name of the object.
[in] nameLengthInBytes The length of objectName (in bytes) not counting the null terminator (null-terminators are not used by the vdsf engine).
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsErrorMsg ( VDS_HANDLE  sessionHandle,
char *  message,
size_t  msgLengthInBytes 
)

Return the error message associated with the last error(s).

If the length of the error message is greater than the length of the provided buffer, the error message will be truncated to fit in the provided buffer.

Caveat, some basic errors cannot be captured, if the provided handles (session handles or object handles) are incorrect (NULL, for example). Without a proper handle, the code cannot know where to store the error...

Parameters:
[in] sessionHandle Handle to the current session.
[out] message Buffer for the error message. Memory allocation for this buffer is the responsability of the caller.
[in] msgLengthInBytes The length of message (in bytes). Must be at least 32 bytes.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsExitSession ( VDS_HANDLE  sessionHandle  ) 

Terminate the current session.

An implicit call to vdsRollback is executed by this function.

Once this function is executed, attempts to use the session handle might lead to memory violation (and, possibly, crashes).

Parameters:
[in] sessionHandle Handle to the current session.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsGetInfo ( VDS_HANDLE  sessionHandle,
vdsInfo *  pInfo 
)

Return information on the current status of the VDS (Virtual Data Space).

The fetched information is mainly about the current status of the memory allocator.

Parameters:
[in] sessionHandle Handle to the current session.
[out] pInfo A pointer to the vdsInfo structure.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsGetStatus ( VDS_HANDLE  sessionHandle,
const char *  objectName,
size_t  nameLengthInBytes,
vdsObjStatus *  pStatus 
)

Return the status of the named object.

Parameters:
[in] sessionHandle Handle to the current session.
[in] objectName The fully qualified name of the object.
[in] nameLengthInBytes The length of objectName (in bytes) not counting the null terminator (null-terminators are not used by the vdsf engine).
[out] pStatus A pointer to the vdsObjStatus structure.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsInitSession ( VDS_HANDLE *  sessionHandle  ) 

This function initializes a session.

It takes one output argument, the session handle.

Upon successful completion, the session handle is set and the function returns zero. Otherwise the error code is returned and the handle is set to NULL.

This function will also initiate a new transaction.

Upon normal termination, the current transaction is rolled back. You MUST explicitly call vdseCommit to save your changes.

Parameters:
[out] sessionHandle The handle to the newly created session.
Returns:
0 on success or a vdsErrors on error.

VDSF_EXPORT int vdsLastError ( VDS_HANDLE  sessionHandle  ) 

Return the last error seen in previous calls (of the current session).

Caveat, some basic errors cannot be captured, if the provided handles (session handles or object handles) are incorrect (NULL, for example). Without a proper handle, the code cannot know where to store the error...

Parameters:
[in] sessionHandle Handle to the current session.
Returns:
The last error.

VDSF_EXPORT int vdsRollback ( VDS_HANDLE  sessionHandle  ) 

Rollback all insertions and deletions (of the current session) executed since the previous call to vdsCommit or vdsRollback.

Insertions and deletions subjected to this call include both data items inserted and deleted from data containers (maps, etc.) and objects themselves created with vdsCreateObj and/or destroyed with vdsDestroyObj.

Note: the internal calls executed by the engine to satisfy this request cannot fail. As such, you cannot find yourself with an ugly situation where some operations were rollbacked and others not. If an error is returned by this function, nothing was rollbacked.

Parameters:
[in] sessionHandle Handle to the current session.
Returns:
0 on success or a vdsErrors on error.

Last updated on April 07, 2008.