WpclsFindObjectNext

This class method finds the next set of objects matching the criteria established by a previous call to wpclsFindObjectFirst.

Syntax

rc = _wpclsFindObjectNext(somSelf, hfind, pBuffer, pCount);

Parameters

somSelf (M_WPObject *) - input

Pointer to the WPObject class object.

hfind (HFIND) - input

Handle associated with a previous wpclsFindObjectFirst or `wpclsFindObjectNext` method call.

pBuffer (POBJECT) - output

Pointer to a buffer that contains an array of object pointers. The buffer must be large enough to hold the number of entries specified by `pCount`.

pCount (PULONG) - in/out

Address of a `ULONG` specifying the number of matching entries requested in `pBuffer`. On return, contains the actual number of entries placed into `pBuffer`.

Returns

rc (BOOL) - returns

Success or error indicator.

Value	Description
TRUE	Successful completion.
FALSE	Error occurred (e.g., `WPERR_OBJECT_NOT_FOUND` or `WPERR_BUFFER_OVERFLOW`).

Remarks

This method returns object pointers (up to the number requested in `pCount`) for objects matching the criteria established by wpclsFindObjectFirst. On output, `pCount` contains the actual number of object pointers returned.

The method uses the find handle (`hfind`) from a previous wpclsFindObjectFirst or `wpclsFindObjectNext` call to continue the search. If `FALSE` is returned, the wpQueryError method can be called to retrieve the error code, such as:

• `WPERR_OBJECT_NOT_FOUND`: No objects matching the specified criteria were found.
• `WPERR_BUFFER_OVERFLOW`: The `pBuffer` was not large enough to hold all matching objects. Call `wpclsFindObjectNext` again to retrieve remaining objects.

The wpclsFindObjectEnd method must be called to terminate the find operation.

How to Override

This method is generally not overridden.

Usage

This method can be called at any time to find the next set of matching objects, typically after wpclsFindObjectFirst returns `WPERR_BUFFER_OVERFLOW`.

Example Code

This example finds all occurrences of an object type in a folder:

#define INCL_WINWORKPLACE
#include <os2.h>

VOID clsFindEverybody(SOMAny *self)
{
    BOOL      rc;                 /* Return from methods */
    HFIND     hFind = 0;          /* Handle for repeated finds */
    CLASS     Class[2];           /* List of classes to look for */
    OBJECT    Object[10];         /* Objects returned from search */
    ULONG     ulCount = 10;       /* Count of objects to find / or found */
    WPFolder  *folder = 0;        /* Pointer to folder for search */
    ULONG     errorid = 0;        /* Error returned from previous search */
    CHAR      sz[CCHMAXPATH];     /* Title string to look for */
    PSZ       title = sz;

    Class[0] = _WPFolder;
    Class[1] = NULL;

    /* Get the pointer to the desktop */
    folder = _wpclsQueryFolder(_WPFolder, "<WP_DESKTOP>", TRUE);
    _wpclsSetError(_WPObject, 0); /* Reset the error indicators */

    /* Attempt to find the first 10 objects matching our criteria */
    ulCount = 10;
    rc = _wpclsFindObjectFirst(_WPObject,  /* Class self pointer */
                               Class,      /* Pointer to array of class objects */
                               &hFind,     /* Handle for wpclsFindObjectNext */
                               NULL,       /* Find EVERYTHING */
                               folder,     /* Pointer to folder of interest */
                               TRUE,       /* Search all folders in tree */
                               NULL,       /* No extended criteria */
                               Object,     /* Array of object pointers */
                               &ulCount);  /* Number requested and number found */

    errorid = _wpclsQueryError(_WPObject); /* Get errorid (may still be OK) */
    if ((!rc && (errorid == WPERR_BUFFER_OVERFLOW)) || rc) {
        /* Process objects found here */
    } else {
        somPrintf("_wpclsFindObjectFirst failed, errorid=%u\n", errorid);
        return;
    }

    do {
        _wpclsSetError(_WPObject, 0); /* Reset error indicators */
        rc = _wpclsFindObjectNext(_WPObject, /* Self */
                                  hFind,     /* Handle from previous Find */
                                  Object,    /* Objects found */
                                  &ulCount); /* Number to look for. On return, number found */

        errorid = _wpclsQueryError(_WPObject);
        if ((!rc && (errorid == WPERR_BUFFER_OVERFLOW)) || rc) {
            /* Process objects found here */
        } else {
            somPrintf("_wpclsFindObjectNext failed, errorid=%u\n", errorid);
            return;
        }
    } while (errorid == WPERR_BUFFER_OVERFLOW);

    _wpclsSetError(_WPObject, 0); /* Reset error indicators */
    rc = _wpclsFindObjectEnd(_WPObject, hFind);
    if (!rc) {
        errorid = _wpclsQueryError(_WPObject);
        somPrintf("_wpclsFindObjectEnd failed, errorid=%u\n", errorid);
        return;
    }
}

Related Methods

• wpclsFindObjectFirst
• wpclsFindObjectEnd
• wpQueryError