LDAPFIRSTMESSAGE(3) LDAPFIRSTMESSAGE(3)

NAME
       ldapfirstmessage,  ldapnextmessage,  ldapcountmessages - Stepping
       through messages in a result chain

LLIIBBRRAARRYY
       OpenLDAP LDAP (libldap, -lldap)

SYNOPSIS
       ##iinncclluuddee <>

       iinntt llddaappccoouunnttmmeessssaaggeess(( LLDDAAPP **lldd,, LLDDAAPPMMeessssaaggee **rreessuulltt ))

       LLDDAAPPMMeessssaaggee **llddaappffiirrssttmmeessssaaggee(( LLDDAAPP **lldd,, LLDDAAPPMMeessssaaggee **rreessuulltt ))

       LLDDAAPPMMeessssaaggee **llddaappnneexxttmmeessssaaggee(( LLDDAAPP **lldd,, LLDDAAPPMMeessssaaggee **mmeessssaaggee ))

DESCRIPTION
       These routines are used to step through the messages in a result  chain
       received  from llddaapprreessuulltt(3)..  For search operations, the result chain
       can contain referral, entry and result  messages.  The  llddaappmmssggttyyppee(3)
       function  can  be  used  to  distinguish  between the different message
       types.

       The llddaappffiirrssttmmeessssaaggee(()) routine is used to retrieve the first  message
       in  a  result  chain.   It  takes  the  result as returned by a call to
       llddaapprreessuulltt(3),, llddaappsseeaarrcchhss(3) or  llddaappsseeaarrcchhsstt(3)  and  returns  a
       pointer to the first message in the result chain.

       This  pointer should be supplied on a subsequent call to llddaappnneexxttmmeess-
       ssaaggee(()) to get the next message, the result of which should be  supplied
       to the next call to llddaappnneexxttmmeessssaaggee(()), etc.  llddaappnneexxttmmeessssaaggee(()) will
       return NULL when there are no more messages.

       These   functions    are    useful    when    using    routines    like
       llddaappppaarrsseerreessuulltt(3)  that  only  operate  on  the  first result in the
       chain.

       A count of the number of messages in the result chain can  be  obtained
       by  calling  llddaappccoouunnttmmeessssaaggeess(()).   It  can also be used to count the
       number of remaining messages in a chain if called with a message, entry
       or  reference  returned by llddaappffiirrssttmmeessssaaggee(()) ,, llddaappnneexxttmmeessssaaggee(()) ,,
       llddaappffiirrsstteennttrryy(3),,    llddaappnneexxtteennttrryy(3),,    llddaappffiirrssttrreeffeerreennccee(3),,
       llddaappnneexxttrreeffeerreennccee(3)..

EERRRROORRSS
       If an error occurs in llddaappffiirrssttmmeessssaaggee(()) or llddaappnneexxttmmeessssaaggee(()), NULL
       is returned.  If  an  error  occurs  in  llddaappccoouunnttmmeessssaaggeess(()),  -1  is
       returned.

SEE ALSO
       llddaapp(3),    llddaappsseeaarrcchh(3),    llddaapprreessuulltt(3),    llddaappppaarrsseerreessuulltt(3),
       llddaappffiirrsstteennttrryy(3), llddaappffiirrssttrreeffeerreennccee(3)

AACCKKNNOOWWLLEEDDGGEEMMEENNTTSS
       OOppeennLLDDAAPP  is  developed  and  maintained  by   The   OpenLDAP   Project
       (http://www.openldap.org/).   OOppeennLLDDAAPP  is  derived  from University of
       Michigan LDAP 3.3 Release.



OpenLDAP 2.2.19                   2004/11/26             LDAPFIRSTMESSAGE(3)