API Reference Pages

Defines, Structures, Typedefs, Functions. More...

Files
file	clHandleApi.h
	Header file of Handle Management related APIs.

Macros
#define	CL_HANDLE_INVALID_VALUE   0x0
	Defines.

Typedefs
typedef ClPtrT	ClHandleDatabaseHandleT
	Handle database handle.

Functions
ClRcT	clHandleCheckin (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClHandleT handle)
	Check in a handle.
ClRcT	clHandleCheckout (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClHandleT handle, CL_OUT void **instance)
	Check out a handle.
ClRcT	clHandleCreate (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClInt32T instanceSize, CL_OUT ClHandleT *handle)
	Creates a handle.
ClRcT	clHandleDatabaseCreate (CL_IN void(*destructor)(void *), CL_OUT ClHandleDatabaseHandleT *databaseHandle)
	Creates a handle database.
ClRcT	clHandleDatabaseDestroy (CL_IN ClHandleDatabaseHandleT databaseHandle)
	Destroys a handle database.
ClRcT	clHandleDestroy (CL_IN ClHandleDatabaseHandleT databaseHandle, CL_IN ClHandleT handle)
	Destroy a handle.

Detailed Description

Defines, Structures, Typedefs, Functions.

Function Documentation

ClRcT clHandleCheckin	(	CL_IN ClHandleDatabaseHandleT	databaseHandle,
		CL_IN ClHandleT	handle
	)

Check in a handle.

Header File

clHandleApi.h

Parameters

databaseHandle	(in) The handle database handle.
handle	(in) The handle.

Return values

CL_OK	The API executed successfully, the returned handle is valid.
CL_ERR_INVALID_HANDLE	Invalid handle database handle, or handle.
CL_ERR_MUTEX_ERROR	Error in securing mutex on the database.

Note

Returned error is a combination of the component id and error code. Use CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.

Description

This API signals the handle database the application is no longer modifying the data assoicated with the handle. Each call to this API negates the effect of exactly one call to the clHandleCheckout() API.

Library File

ClUtil

See Also

clHandleCreate, clHandleCheckout(), clHandleDestroy()

ClRcT clHandleCheckout	(	CL_IN ClHandleDatabaseHandleT	databaseHandle,
		CL_IN ClHandleT	handle,
		CL_OUT void **	instance
	)

Check out a handle.

Header File

clHandleApi.h

Parameters

databaseHandle	(in) The handle database handle.
handle	(in) The handle.
instance	(out) A pointer to return the pointer to the data.

Return values

CL_OK	The API executed successfully, the returned handle is valid.
CL_ERR_INVALID_HANDLE	Invalid handle database handle, or handle.
CL_ERR_MUTEX_ERROR	Error in securing mutex on the database.

Note

Returned error is a combination of the component id and error code. Use CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.

Description

This API returns with a pointer that point to the data associated with the handle and increments the check-out counter of the handle. An application should call this function before making modifications to the handle data.

Library File

ClUtil

See Also

clHandleCreate, clHandleCheckout(), clHandleDestroy()

ClRcT clHandleCreate	(	CL_IN ClHandleDatabaseHandleT	databaseHandle,
		CL_IN ClInt32T	instanceSize,
		CL_OUT ClHandleT *	handle
	)

Creates a handle.

Header File

clHandleApi.h

Parameters

databaseHandle	(in) The handle database handle.
instanceSize	(in) Size of memory to be allocated.
handle	(out) Pointer to return the unique handle.

Return values

CL_OK	The API executed successfully, the returned handle is valid.
CL_ERR_INVALID_HANDLE	Invalid handle database handle.
CL_ERR_MUTEX_ERROR	Error in securing mutex on the database.
CL_ERR_NO_RESOURCE	The database is already marked for destroy (perhaps on another thread), so it is not allowed to create new handles.
CL_ERR_NO_MEMORY	Could not allocated memory for handle or data

Note

Returned error is a combination of the component id and error code. Use CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.

Description

This API creates a new handle, unique within the context of the given handle database. It also allocates memory of given size for data that the application can use to store any data associated with this handle.

Library File

ClUtil

See Also

clHandleCreate, clHandleCheckout(), clHandleDestroy()

ClRcT clHandleDatabaseCreate	(	CL_IN void(*)(void *)	destructor,
		CL_OUT ClHandleDatabaseHandleT *	databaseHandle
	)

Creates a handle database.

Header File

clHandleApi.h

Parameters

destructor	(in) An optional pointer to a destructor function. Called when a handle is to be destroyed with its associated data. If the data is in one monolithic dynamically allocated block, the destructor is not needed. If the data has pointers pointing to separately allocated memory blocks, the destructrore should be provided and should be responsible to clean-up the auxiliary data.
databaseHandle	(out) A pointer to get a unique handle back that can be used in subsequent calls to the handle database.

Return values

CL_OK	The API executed successfully, the returned handle is valid.
CL_ERR_NO_MEMORY	Memory allocation failure.

Note

Returned error is a combination of the component id and error code. Use CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.

Description

This API creates and initializes a handle database.

Library File

ClUtil

See Also

clHandleCreate, clHandleCheckout(), clHandleDestroy()

ClRcT clHandleDatabaseDestroy

(

CL_IN ClHandleDatabaseHandleT

databaseHandle

)

Destroys a handle database.

Header File

clHandleApi.h

Parameters

databaseHandle

(in) The handle database handle.

Return values

CL_OK	The API executed successfully, the returned handle is valid.
CL_ERR_INVALID_HANDLE	Invalid handle.
CL_ERR_MUTEX_ERROR	Error in securing mutex on the database.

Note

Returned error is a combination of the component id and error code. Use CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.

Description

This API destroys and frees all data associated with a handle database.

Library File

ClUtil

See Also

clHandleCreate, clHandleCheckout(), clHandleDestroy()

ClRcT clHandleDestroy	(	CL_IN ClHandleDatabaseHandleT	databaseHandle,
		CL_IN ClHandleT	handle
	)

Destroy a handle.

Header File

clHandleApi.h

Parameters

databaseHandle	(in) The handle database handle.
handle	(in) The handle.

Return values

CL_OK	The API executed successfully, the returned handle is valid.
CL_ERR_INVALID_HANDLE	Invalid handle database handle or handle.
CL_ERR_MUTEX_ERROR	Error in securing mutex on the database.

Note

Returned error is a combination of the component id and error code. Use CL_GET_ERROR_CODE(RET_CODE) defined in clCommonErrors.h to get the error code.

Description

This API destroys (recycles) a given handle, releasing not only the handle, but also the data (memory) allocated in association with the handle. If a desructor function was provided at the time when the database was created, the destructor function is called before the handle data is freed.

If the handle is checked out by the application when this API is called, then the destruction of the handle will be delayed until no further checkouts are pending.

Library File

ClUtil

See Also

clHandleCreate, clHandleCheckout(), clHandleDestroy()