VMS Help DCE_SECURITY, API Routines, rdacl_get_referral  *Conan The Librarian (sorry for the slow response - running on an old VAX)

 NAME
   rdacl_get_referral - Gets a referral to an ACL update site

 SYNOPSIS

   #include <dce/rdaclif.h>

   void rdacl_get_referral(
           handle_t h,
           sec_acl_component_name_t component_name,
           uuid_t *manager_type,
           sec_acl_type_t sec_acl_type,
           sec_acl_tower_set_t *towers[],
           error_status_t *status);

 PARAMETERS

   Input

   h      A handle referring to the target object.

   component_name
          A character string containing the name of the target object.

   manager_type
          A pointer to the UUID identifying the type of the ACL manager
          in question. There may be more than one type of ACL manager
          protecting the object whose ACL is bound to the input handle.
          Use this parameter to distinguish them.  Use
          sec_acl_get_manager_types() to acquire a list of the manager
          types protecting a given object.

   sec_acl_type
          The ACL type. The sec_acl_type_t data type distinguishes the
          various types of ACLs an object can possess for a given manager
          type.  The possible values are as follows:

            +  sec_acl_type_object

            +  sec_acl_type_default_object

            +  sec_acl_type_default_container

   Output

   towers[]
          A pointer to address information indicating an ACL update site.
          This information, obtained from the RPC runtime, is used by the
          client-side code to construct a new ACL binding handle indicating
          a site that will not return the sec_acl_site_readonly error.
          The sec_acl_tower_set_t structure contains an array of towers
          (called towers[]) and an unsigned 32-bit integer indicating the
          number of array elements (called count). This type enables the
          client to pass in an unallocated array of towers and have the
          server allocate the correct amount.

   status
          A pointer to the completion status.  On successful completion,
          the routine returns error_status_ok. Otherwise, it returns an
          error.

 DESCRIPTION

   The rdacl_get_referral() routine obtains a referral to an ACL update
   site.  This function is used when the current ACL site yields a
   sec_acl_site_readonly error. Some replication managers will require all
   updates for a given object to be directed to a given replica.  If
   clients of the generic ACL interface know they are dealing with an
   object that is replicated in this way, this function allows them to
   recover from the problem and rebind to the proper update site. The DCE
   network registry, for example, is replicated this way.

 NOTES

   This call is not intended to be used by application programs.  The
   sec_acl Application Programming Interface (API) provides all the
   functionality necessary to use the ACL facility. This reference page
   is provided for programmers who wish to write an ACL manager.  In
   order to write an ACL manager, a programmer must implement the entire
   rdacl interface.

   This network interface is called on the client side via the sec_acl
   local interface. Developers are responsible for implementing the server
   side of this interface. Test server code is included as a sample
   implementation.

 FILES
     SYS$COMMON:[DCE$LIBRARY]RDACLIF.IDL
                The idl file from which dce/rdaclif.h was derived.

 ERRORS

   sec_acl_unknown_manager_type
                The manager type selected is not an available option.

   error_status_ok
                The call was successful.

 RELATED INFORMATION

   Functions: sec_intro