cwbOBJ_CreateListHandle

Purpose

Allocates a handle for a list of objects. After a list handle has been allocated, the filter criteria may be set for the list with the cwbOBJ_SetListFilter() API, the list may be built with the cwbOBJ_OpenList() API, etc. cwbOBJ_DeleteListHandle() should be called to deallocated this list handle and free any resources used by it.

Syntax

 
unsigned int CWB_ENTRY  cwbOBJ_CreateListHandle(
                               const char         *systemName,
                               cwbOBJ_ListType     type,
                               cwbOBJ_ListHandle  *listHandle,
                               cwbSV_ErrHandle     errorHandle);

Parameters

const char *systemName - input

Pointer to the system name contained in ASCIIZ string

cwbOBJ_ListType type - input

Type of list to allocate (eg. spooled file list, output queue list, etc).

cwbOBJ_ListHandle *listHandle - output

Pointer to a list handle that will be passed back on output. This handle is needed for other calls using the list.

cwbSV_ErrHandle errorHandle - output

Optional, may be 0. Any returned messages will be written to this object. It is created with the cwbSV_CreateErrHandle() API. The messages may be retrieved through the cwbSV_GetErrText() API. If the parameter is set to zero, no messages will be retrievable.

Return Codes

The following list shows common return values.

CWB_NO_ERROR

Successful completion.

CWB_NOT_ENOUGH_MEMORY

Insufficient memory.

CWB_NON_REPRESENTABLE_UNICODE_CHAR

One or more input Unicode characters have no representation in the codepage that is being used.

CWB_API_ERROR

General API failure.

Usage

Caller must call cwbOBJ_DeleteListHandle when done using this list handle. Typical calling sequence for retrieving a list of objects would be:

1. cwbOBJ_CreateListHandle()
2. cwbOBJ_SetListFilter() { repeated as needed }
3. cwbOBJ_OpenList()
4. cwbOBJ_GetListSize() to get the size of the list.
5. For n=0 to list size - 1 cwbOBJ_GetObjHandle for list item in position n do something with the object cwbOBJ_DeleteObjHandle()
6. cwbOBJ_CloseList() - You may go back to step 2 here.
7. cwbOBJ_DeleteListHandle()