NAME

   rpc_ns_profile_elt_add - Adds an element to a profile; if necessary,
                            creates the entry

   Used by client, server, or management applications.

 SYNOPSIS

   #include <dce/rpc.h>

   void rpc_ns_profile_elt_add( unsigned32 profile_name_syntax,
                                unsigned_char_t *profile_name,
                                rpc_if_id_t *if_id,
                                unsigned32 member_name_syntax,
                                unsigned_char_t *member_name,
                                unsigned32 priority,
                                unsigned_char_t *annotation,
                                unsigned32 *status );

 PARAMETERS

   Input

   profile_name_syntax
       An integer value that specifies the syntax of the
       profile_name parameter.  To use the syntax specified
       in the RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
       rpc_c_ns_syntax_default.

   profile_name
       Specifies the RPC profile that receives a new element.  This can
       be either the global or cell-relative name.

   if_id
       Specifies the interface identifier of the new profile element.
       To add or replace the default profile element, specify NULL.

   member_name_syntax
       An integer value that specifies the syntax of
       member_name.  To use the syntax specified in the
       RPC_DEFAULT_ENTRY_SYNTAX logical name, provide
       rpc_c_ns_syntax_default.

   member_name
       Specifies the entry in the name service database to include in
       the new profile element.  This can be either the global or cell-
       relative name.

   priority
       An integer value (0 to 7) that specifies the relative priority
       for using the new profile element during the import and lookup
       operations.  A value of 0 (zero) is the highest priority.  A
       value of 7 is the lowest priority.  Two or more elements can have
       the same priority.  When adding the default profile member, use
       a value of 0 (zero).

   annotation
       Specifies an annotation string that is stored as part of the new
       profile element. The string can be up to 17 characters long.
       Specify NULL or the string \0 if there is no annotation string.
       The string is used by applications for informational purposes
       only. For example, an application can use this string to store
       the interface name string (specified in the IDL file).
       DCE RPC does not use this string during lookup or import
       operations, or for enumerating profile elements.

   Output

   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_incomplete_name
                      Incomplete name.

       rpc_s_invalid_name_syntax
                      Invalid name syntax.

       rpc_s_invalid_priority
                      Invalid profile element priority.

       rpc_s_name_service_unavailable
                      Name service unavailable.

       rpc_s_no_ns_permission
                      No permission for name service operation.

       rpc_s_unsupported_name_syntax
                      Unsupported name syntax.

 DESCRIPTION

   The rpc_ns_profile_elt_add() routine adds an element to the profile
   attribute of the entry in the name service database specified by the
   profile_name parameter.

   If the profile_name entry does not exist, this routine creates the
   entry with a profile attribute and adds the profile element specified
   by the if_id, member_name, priority, and annotation parameters. In
   this case, the application must have permission to create the entry.
   Otherwise, a management application with the necessary permissions
   creates the entry by calling rpc_ns_mgmt_entry_create() before the
   application is run.

   If an element with the specified member name and interface identifier
   are already in the profile, this routine updates the element's
   priority and annotation string using the values provided in the
   priority and annotation parameters.

   An application can add the entry in the member_name parameter to a
   profile before it creates the entry itself.

   Permissions Required

   You need both read permission and write permission to the CDS object
   entry (the target profile entry).  If the entry does not exist, you
   also need insert permission to the parent directory.

 RETURN VALUES

   No value is returned.

 RELATED INFORMATION

   Functions: rpc_if_inq_id
              rpc_ns_mgmt_entry_create
              rpc_ns_profile_elt_remove