NAME

   rpc_ns_binding_import_next - Returns a binding handle of a compatible
                                server (if found) from the name service
                                database

   Used by client applications.

 SYNOPSIS

   #include <dce/rpc.h>

   void rpc_ns_binding_import_next( rpc_ns_handle_t import_context,
                                    rpc_binding_handle_t *binding,
                                    unsigned32 *status );

 PARAMETERS

   Input

   import_context
       Specifies a name service handle.  This handle is returned from
       the rpc_ns_binding_import_begin() routine.

   Output

   binding
       Returns a compatible server binding handle.

   status
       Returns the status code from this routine.  This status code
       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_import_next() routine returns one compatible (to
   the client) server binding handle selected at random from the name
   service database.  The server offers the interface and object UUID
   specified by the respective if_handle and obj_uuid parameters in
   rpc_ns_binding_import_begin().

   A similar routine is rpc_ns_binding_lookup_next(), which returns a
   vector of compatible server binding handles for one or more servers.

   NOTE:  Routine rpc_ns_binding_import_next() calls routine
          rpc_ns_binding_lookup_next() which, in turn, obtains a vector
          of server binding handles from the name service database.
          Next, routine rpc_ns_binding_import_next() randomly selects one
          of the elements from the vector.

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

   The returned compatible binding handle always contains an object UUID.
   Its value depends on the value specified in the obj_uuid parameter of
   the rpc_ns_binding_import_begin() routine, as follows:

     +  If obj_uuid contains a non-nil object UUID, the returned binding
        handle contains that object UUID.

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

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

          - If the server exported one object UUID, the 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 multiple calls to
          rpc_ns_binding_import_next() returning different object UUIDs.
          In particular, note that each name service entry stores server
          address information separately from exported object UUIDs.
          Successive calls to rpc_ns_binding_import_next() using the same
          import context 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

   The client application can use the returned binding handle to make
   a remote procedure call to the server. If the client fails to
   communicate with the server, it can call the
   rpc_ns_binding_import_next() routine again.

   Each time the client calls rpc_ns_binding_import_next(), the routine
   returns another server binding handle.  The binding handles returned
   are unordered.  Multiple binding handles can refer to different
   protocol sequences from the same server.

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

   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_import_next() routine allocates memory for the
   returned binding parameter. When a client application finishes with
   the binding handle, it must call rpc_binding_free() to deallocate the
   memory.  Each call to rpc_ns_binding_import_next() requires a
   corresponding call to rpc_binding_free().

   The client calls the rpc_ns_binding_import_done() routine after it has
   satisfactorily used one or more returned server binding handles.  The
   rpc_ns_binding_import_done() routine deletes the import context.  The
   client also calls rpc_ns_binding_import_done() if the application
   wants to start a  new  search  for  compatible  servers  (by  calling
   rpc_ns_binding_import_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_ns_binding_import_begin
              rpc_ns_binding_import_done
              rpc_ns_binding_inq_entry_name
              rpc_ns_binding_lookup_begin
              rpc_ns_binding_lookup_done
              rpc_ns_binding_lookup_next
              rpc_ns_binding_select