CWBSO_CopyObjHandle

Use the CWBSO_CopyObjHandle API with this product.

Purpose

Creates a new instance of an object and returns a handle to the new instance. This does not create a new system object. It merely creates an additional instance of a system object on the client. Object handles that are returned by CWBSO_GetObjHandle are always destroyed when the list that contains the object is closed. This API allows the creation of an instance of the object that will persist after the list is closed. The object instance that was created by this API is kept in sync with the object in the list. In other words, if one of the objects is changed, the changes will be apparent in the other object.

Syntax

 
unsigned int CWB_ENTRY CWBSO_CopyObjHandle(
                CWBSO_OBJ_HANDLE objectHandle,          
                CWBSO_OBJ_HANDLE far* lpNewObjectHandle);

Parameters

CWBSO_OBJ_HANDLE objectHandle - input: A handle to an object that was returned by a previous call to CWBSO_GetObjHandle or CWBSO_CopyObjHandle.
CWBSO_OBJ_HANDLE far* lpNewObjectHandle - output: A long pointer to a handle which is set to a new handle for the same sytem object. This handle may be used with any other API that accepts an object handle with the exception that some APIs only operate on specific types of objects.

Return Codes

The following list shows common return values.

CWBSO_NO_ERROR: No error occurred.
CWBSO_LOW_MEMORY: Not enough memory is available for the request.
CWBSO_BAD_OBJ_HANDLE: The object handle that is specified is not valid.

Usage

CWBSO_GetObjHandle or CWBSO_CopyObjHandle must be called prior to calling this API. The object handle that is returned by CWBSO_GetObjHandle or CWBSO_CopyObjHandle must be passed as input to this API. When the object is no longer needed, the calling program is responsible for doing the following:

Call CWBSO_DeleteObjHandle to free up resources that are allocated on the client.