cwbUP_FindEntry

Purpose

Gets a handle to an existing update entry by using entrySource and entryTarget as the search parameters.

Syntax

 
unsigned int CWB_ENTRY cwbUP_FindEntry(
                             char * entrySource,
                             char * entryTarget,
                             unsigned long *searchStart,
                             cwbUP_EntryHandle *entryHandle);

Parameters

char * entrySource - input

Points to a null-terminated string that contains the source for the update entry. This can be either a drive and path, or a UNC name. This string will be used to search for a */ matching update entry.

char * entryTarget - input

Points to a null-terminated string that contains the target for the update entry. This can be either a drive and path, or a UNC name. This string will be used to search for a matching update entry.

unsigned long * searchStart - input/output

Pointer to an index into the list of update entries to begin the search at. This would be used in cases where multiple update entries may have matching source and targets. You would use this parameter to "skip" over entries in the search, and continue on searching for a matching update entry that is after searchStart in the list. On successful return, searchStart will be set to the position in the list where the update entry was found. This should be set to CWBUP_SEARCH_FROM_BEGINNING if you want to search all update entries.

cwbUP_EntryHandle * entryHandle - input/output

Pointer to a cwbUP_EntryHandle where the handle will be returned. This handle must be used in subsequent calls to the update entry APIs.

Return Codes

The following list shows common return values.

CWB_OK

Successful completion.

CWB_INVALID_POINTER

NULL passed as an address.

CWB_NOT_ENOUGH_MEMORY

Insufficient memory to create handle.

CWBUP_SEARCH_POSITION_ERROR

Search starting position is not valid.

CWBUP_ENTRY_NOT_FOUND

No update entry matched search value.

CWBUP_STRING_TOO_LONG

An input string is longer than the maximum of CWBUP_MAX_LENGTH.

Usage

The handle that is returned from this call will be used for accessing the update entry with other Update APIs. When you use this call, and have completed your processing of the update entry, you must call cwbUP_FreeEntryHandle. This call will "unlock" the entry, and free resources with which it is associated.