DL_DataGetNext

NAME
  DL_DataGetNext, CSSM_DL_DataGetNext - Get next data record (CDSA)

SYNOPSIS
  # include <cssm.h>

   API:
       CSSM_RETURN CSSMAPI CSSM_DL_DataGetNext
       (CSSM_DL_DB_HANDLE DLDBHandle,
       CSSM_HANDLE ResultsHandle,
       CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
       CSSM_DATA_PTR Data,
       CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)
   SPI:
       CSSM_RETURN CSSMDLI DL_DataGetNext
       (CSSM_DL_DB_HANDLE DLDBHandle,
       CSSM_HANDLE ResultsHandle,
       CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
       CSSM_DATA_PTR Data,
       CSSM_DB_UNIQUE_RECORD_PTR *UniqueId)

LIBRARY
  Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE)

PARAMETERS
  DLDBHandle (input)
          The handle pair that describes the add-in data storage
          library module to be used to perform this function, and
          the open data store from which records were selected by
          the initiating query.

  ResultsHandle (input)
          The handle identifying a set of records retrieved by a query
          executed by the CSSM_DL_DataGetFirst() function.

  Attributes (optional-input/output)
          If the Attributes structure pointer is NULL, no values are
          returned.

          Otherwise, the DataRecordType, NumberOfAttributes and
          AttributeData fields are read.  AttributeData must be an
          array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE elements.
          Only the Info field of each element is used on input. The
          AttributeFormat field of the Info field is ignored on input.

          On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a
          list of all or the requested attribute values (subset) from
          the retrieved record.  The SemanticInformation field is set.
          For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData
          array, the NumberOfValues field is set to reflect the size of
          the Value array which is allocated by the DL using the
          application specified allocators.  Each CSSM_DATA in the Value
          array will have it's Data field as a pointer to data allocated
          using the application specified allocators containing the
          attributes value, and have it's Length set to the length of
          the value.

          All values for an attribute are returned (this could be 0).
          All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA are
          left unchanged except for the AttributeFormat field, which is
          set to reflect the schema.

  Data (optional-input/output)
          Data values contained in the referenced memory are ignored
          during processing and are overwritten with the retrieved
          opaque object. On output, a CSSM_DATA structure containing
          the opaque object stored in the retrieved record. If the
          pointer is data structure pointer is NULL, the opaque object
          is not returned.

  UniqueId (output)
          If successful and (at least) a record satisfying the query
          has been found, then this parameter returns a pointer to a
          CSSM_UNIQUE_RECORD_PTR structure containing a unique
          identifier associated with the retrieved record. This unique
          identifier structure can be used in future references to this
          record using this DLDBHandle pairing. It may not be valid for
          other DLHandles targeted to this DL module or to other
          DBHandles targeted to this data store. If there are no more
          records satisfying the query, then this pointer is NULL and
          CSSM_DL_DataGetNext() must return CSSM_DL_ENDOFDATA; in this
          case a normal termination condition has occurred. The
          CSSM_DL_FreeUniqueRecord() must be used to de-allocate this
          structure.

DESCRIPTION
  This function returns the next data record referenced by the
  ResultsHandle.  The ResultsHandle references a set of records
  selected by an invocation of the DataGetFirst function. The
  Attributes parameter can specify a subset of the attributes to be
  returned. If Attributes specifies an attribute that is not defined
  in the database's meta-information, an error condition is returned.
  The record values are returned in the Attributes and Data parameters.
  The output buffers for the retrieved record are allocated by this
  function using the memory management functions provided during the
  module attach operation. The function also returns a unique record
  identifier for the return record.

  The data storage module supports one of two retrieval models:
  transactional or file system scan. The transactional model freezes
  the set of records to be retrieved at query initiation. The file
  system scan model selects from a potentially changing set of records
  during the retrieval process. The EndOfDataStore() function indicates
  when all matching records have been retrieved. The caller can
  determine which retrieval model is supported by examining the
  encapsulated product description for this data storage module.  Once
  a user has finished using a certain query, it must call
  CSSM_DataAbortQuery() for releasing resources that CSSM uses. If all
  records satisfying the query have been retrieved, then query is
  automatically terminated.

RETURN VALUE
  A CSSM_RETURN value indicating success or specifying a particular
  error condition. The value CSSM_OK indicates success. All other
  values represent an error condition.

ERRORS
  Errors are described in the CDSA technical standard.  See CDSA.

       CSSMERR_DL_ENDOFDATA
       CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE
       CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT
       CSSMERR_DL_INVALID_DB_HANDLE
       CSSMERR_DL_INVALID_FIELD_NAME
       CSSMERR_DL_INVALID_RECORDTYPE
       CSSMERR_DL_INVALID_RECORD_UID
       CSSMERR_DL_INVALID_RESULTS_HANDLE

SEE ALSO
  Books

  Intel CDSA Application Developer's Guide (see CDSA)

  Other Help Topics

  Functions for the CSSM API:

      CSSM_DL_DataGetFirst
      CSSM_DL_DataAbortQuery

  Functions for the DL SPI:

      DL_DataGetFirst
      DL_DataAbortQuery