wpclsFindObjectFirst

This class method is called to find workplace objects.

Syntax

_wpclsFindObjectFirst(somSelf, pClasslist, phFind, pszTitle, Folder, fSubfolders, pExtendedCriteria, pBuffer, pCount)

Parameters

somSelf (M_WPObject *) - input: Pointer to the WPObject class object.

pClasslist (PCLASS) - output: Pointer to an array of class objects. The final element of the array must be NULL. If specified, only objects descended from the specified object classes are returned.

phFind (PHFIND) - output: Address of the handle returned by this method. This handle is used with subsequent calls to wpclsFindObjectNext and wpclsFindObjectEnd.

pszTitle (PSZ) - input: Pointer to the title specification for objects to be searched. May include wildcard characters * and ?. If specified, only objects whose titles match the title specification are returned.

Folder (WPFolder *) - input: Pointer to the folder in which to find objects. Can be determined by issuing a call to the wpclsQueryFolder method.

fSubfolders (BOOL) - input

Scope indicator.

TRUE: Search Folder and all folders in its tree.
FALSE: Search only the folder specified by Folder.

pExtendedCriteria (PVOID) - input: Pointer to the extended search criteria. Points to a buffer containing class-specific extended search criteria. If specified, only objects matching the criteria are returned. If NULL, objects of all classes are returned.

pBuffer (POBJECT) - output: Pointer to a buffer that contains an array of object pointers. Must be large enough to hold the number of requested entries specified by pCount.

pCount (PULONG) - in/out: Address of the number of matching entries requested in pBuffer. On return, contains the number of entries placed into pBuffer.

Returns

rc (BOOL) - returns

Success indicator.

TRUE: Successful completion.
FALSE: Error occurred. Call wpQueryError to retrieve the error code. Possible error codes include:
WPERR_BUFFER_OVERFLOW: The pBuffer was not large enough to fit all objects matching the specified criteria. Call wpclsFindObjectNext to retrieve the remaining objects.
WPERR_OBJECT_NOT_FOUND: No objects matching the specified criteria were found.

Remarks

This method returns object pointers (up to the number requested in pCount) for objects that match the specifications and fit in pBuffer. On output, pCount contains the actual number of object pointers returned. The returned objects are all locked; the wpUnlockObject method must be called for each object when finished.

The wpclsFindObjectNext method uses the find object handle returned by this method to continue the search. The wpclsFindObjectEnd method should 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 objects.

Example Code

This example code finds all folders contained in the Desktop subtree.

#define INCL_WINWORKPLACE
#include <os2.png>

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);

  /* Reset the error indicators */
  _wpclsSetError(_WPObject, 0);

  rc = 0;
  /* Attempt to find the first 10 objects matching the 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 */

  /* Get the errorid */
  errorid = _wpclsQueryError(_WPObject);

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

  do
  {
    /* Reset error indicators */
    _wpclsSetError(_WPObject, 0);

    rc = 0;
    /* Look for the next 10 objects */
    ulCount = 10;
    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 all objects found here */
    }
    else
    {
      somPrintf("_wpclsFindObjectNext failed, errorid=%u\n", errorid);
      return;
    }
  }
  while (errorid == WPERR_BUFFER_OVERFLOW);

  /* Reset the error indicators */
  _wpclsSetError(_WPObject, 0);

  rc = 0;
  /* Indicate find complete */
  rc =_wpclsFindObjectEnd(_WPObject, hFind);
  if (!rc)
  {
    errorid = _wpclsQueryError(_WPObject);
    somPrintf("_wpclsFindObjectEnd failed, errorid=%u\n", errorid);
    return;
  }
  return;
}

Related Methods