NAME

   rpc_ns_binding_lookup_next - Returns a list of binding handles of
                                one or more compatible servers (if
                                found) from the name service database

   Used by client applications.

 SYNOPSIS

   #include <dce/rpc.h>

   void rpc_ns_binding_lookup_next( rpc_ns_handle_t lookup_context,
                                    rpc_binding_vector_t **binding_vec,
                                    unsigned32 *status );

 PARAMETERS

   Input

   lookup_context
        Specifies a name service handle. This handle is returned from the
        rpc_ns_binding_lookup_begin() routine.

   Output

   binding_vec
        Returns a vector of compatible server binding handles.

   status
        Returns the status code from this routine, which indicates
        whether the routine completed successfully or, if not, why not.
        The possible status codes and their meanings are as follows:

        rpc_s_ok       Success.

        rpc_s_class_version_mismatch
                       RPC class version mismatch.

        rpc_s_entry_not_found
                       Name service entry not found.

        rpc_s_invalid_ns_handle
                       Invalid name service handle.

        rpc_s_name_service_unavailable
                       Name service unavailable.

        rpc_s_no_more_bindings
                       No more bindings.

        rpc_s_no_ns_permission
                       No permission for name service operation.

        rpc_s_not_rpc_entry
                       Not an RPC entry.

 DESCRIPTION

   The rpc_ns_binding_lookup_next() routine returns a vector of
   compatible (to the client) server binding handles.  The servers offer
   the interface and object UUID specified by the respective if_handle
   and object_uuid parameters in rpc_ns_binding_lookup_begin().  The
   number of binding handles that rpc_ns_binding_lookup_next() attempts
   to return is the value of binding_max_count in the
   rpc_ns_binding_lookup_begin() routine.

   A similar routine is rpc_ns_binding_import_next(), which returns one
   compatible server binding handle.

   The rpc_ns_binding_lookup_next() routine communicates only with the
   name service database, not directly with servers.

   This routine traverses entries in the name service database, returning
   compatible server binding handles from each entry.  The routine can
   return multiple binding handles from each entry.  The search operation
   obeys the following rules for traversing the entries:

     +  At each entry visited, the search operation randomly processes
        binding information, then group members, then profile members.
        Profile members with different priorities are returned according
        to their priorities, highest priority first.

     +  The search operation returns members of a group in random order.

     +  The search operation returns members of a profile with the same
        priority in random order.

   If the entry where the search begins (see the entry_name parameter in
   rpc_ns_binding_lookup_begin()) contains binding handles as well as an
   RPC group and/or a profile, rpc_ns_binding_lookup_next() returns the
   binding handles from entry_name before searching the group or profile.
   This means that rpc_ns_binding_lookup_next() can return a partially
   full vector before processing the members of the group or profile.

   Each binding handle in the returned vector always contains an object
   UUID.  Its value depends on the value specified in the object_uuid
   parameter of rpc_ns_binding_lookup_begin() as follows:

     +  If object_uuid contains a non-nil object UUID, each returned
        binding handle contains that object UUID.

     +  If object_uuid contains a nil object UUID or NULL, the object
        UUID returned in each binding handle depends on how the server
        exported object UUIDS:

          - If the server did not export any object UUIDs, each returned
            binding handle contains a nil object UUID.

          - If the server exported one object UUID, each returned
            binding handle contains that object UUID.

          - If the server exported multiple object UUIDs, the returned
            binding handle contains one of the object UUIDs, selected
            in an unspecified way.

          Applications should not count on the binding handles returned
          from a given entry to contain different object UUIDs.  In
          particular, note that each name service entry stores server
          address information separately from exported object UUIDs.
          One or more calls to rpc_ns_binding_lookup_next() will return
          exactly one binding for each compatible server address, not
          the cross product of all compatible server addresses with all
          exported UUIDs.  Each returned binding will contain one of the
          exported object UUIDs, but applications should not count on
          any specific selection mechanism for these object UUIDs

   From the returned vector of server binding handles, the client
   application can employ its own criteria for selecting individual
   binding handles, or the application can call rpc_ns_binding_select()
   to select a binding handle.  The rpc_binding_to_string_binding() and
   rpc_string_binding_parse() routines are useful for a client creating
   its own selection criteria.

   The client application can use the selected binding handle to attempt
   a remote procedure call to the server. If the client fails to
   communicate with the server, it can select another binding handle
   from the vector.  When all the binding handles in the vector are used,
   the client application calls rpc_ns_binding_lookup_next() again.

   Each time the client calls rpc_ns_binding_lookup_next(), the routine
   returns another vector of binding handles.  The binding handles
   returned in each vector are unordered, as is the order in which the
   vectors are returned from multiple calls to this routine.

   When looking up compatible binding handles from a profile, the binding
   handles from entries of equal profile priority are unordered in the
   returned vector.  In addition, the vector returned from a call to
   rpc_ns_binding_lookup_next() contains only compatible binding handles
   from entries of equal profile priority. This means the returned vector
   may be partially full.

   For  example,  if  the  binding_max_count  parameter  value  in
   rpc_ns_binding_lookup_begin() was 5 and rpc_ns_binding_lookup_next()
   finds only three compatible binding handles from profile entries of
   priority 0 (zero), rpc_ns_binding_lookup_next() returns a partially
   full binding vector (with three binding handles).  The next call to
   rpc_ns_binding_lookup_next() creates a new binding vector and begins
   looking for compatible binding handles from profile entries of
   priority 1.

   When the search finishes, the routine returns a  status  code  of
   rpc_s_no_more_bindings and returns the value NULL in binding_vec.

   A client application calls rpc_ns_binding_inq_entry_name() to obtain
   the name of the entry in the name service database where the binding
   handle came from.

   The rpc_ns_binding_lookup_next() routine allocates memory for the
   returned binding_vec.  When a client application finishes with the
   vector, it must call rpc_binding_vector_free() to deallocate the
   memory.  Each call to rpc_ns_binding_lookup_next() requires a
   corresponding call to rpc_binding_vector_free().

   The client calls rpc_ns_binding_lookup_done(), which deletes the
   lookup context.  The client also calls rpc_ns_binding_lookup_done()
   if the application wants to start a new search for compatible
   servers (by calling rpc_ns_binding_lookup_begin()).  The order of
   binding handles returned can be different for each new search. This
   means that the order in which binding handles are returned to an
   application can be different each time the application is run.

   Permissions Required

   You need read permission to the specified CDS object entry (the
   starting name service entry) and to any CDS object entry in the
   resulting search path.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_binding_to_string_binding
              rpc_binding_vector_free
              rpc_ns_binding_import_next
              rpc_ns_binding_inq_entry_name
              rpc_ns_binding_lookup_begin
              rpc_ns_binding_lookup_done
              rpc_ns_binding_select
              rpc_string_binding_parse