NAME
   sec_rgy_pgo_get_members - Returns the membership list for a specified
                             group or organization or returns the set of
                             groups in which the specified principal is
                             a member.

 SYNOPSIS

 #include <dce/pgo.h>

 void sec_rgy_pgo_get_members(
         sec_rgy_handle_t context,
         sec_rgy_domain_t name_domain,
         sec_rgy_name_t go_name,
         sec_rgy_cursor_t *member_cursor,
         signed32 max_members,
         sec_rgy_member_t member_list[],
         signed32 *number_supplied,
         signed32 *number_members,
         error_status_t *status);

 PARAMETERS

 Input

 context
        An opaque handle bound to a secd server. Use sec_rgy_site_open()
        to acquire a bound handle.

 name_domain
        This variable specifies whether go_name identifies a principal,
        group, or organization.  The valid values are as follows:

        sec_rgy_domain_group
                    The go_name parameter identifies a group.

        sec_rgy_domain_org
                    The go_name parameter identifies an organization.

        sec_rgy_domain_person
                    The go_name parameter identifies an principal.

 go_name
        A character string (type sec_rgy_name_t) that contains the name
        of a group, organization, or principal.  If go_name is the name
        of a group or organization, the call returns the group's or
        organization's member list. If go_name is the name of a
        principal, the call returns a list of all groups in which the
        principal is a member. (Contrast this with the
        sec_rgy_acct_get_proj call, which returns only those groups in
        which the principal is a member and that have been marked to be
        included in the principal's project list.)

 max_members
        A signed32 variable containing the allocated dimension of the
        member_list[] array. This is the maximum number of members or
        groups that can be returned by a single call.

 Input/Output

 member_cursor
        An opaque pointer to a specific entry in the membership list
        or list of groups.  The returned list begins with the entry
        specified by member_cursor. Upon return, the cursor points to
        the next entry after the last one returned.  If there are no
        more entries, the routine returns the value
        sec_rgy_no_more_entries in the status parameter.  Use
        sec_rgy_cursor_reset() to reset the cursor to the beginning
        of the list.

 Output

 member_list[]
        An array of character strings to receive the returned member
        or group names. The size allocated for the array is given by
        max_number. If this value is less than the total number of
        members or group names, multiple calls must be made to return
        all of the members or groups.

 number_supplied
        A pointer to a signed32 variable to receive the number of
        members or groups actually returned in member_list[].

 number_members
        A pointer to a signed32 variable to receive the total number
        of members or groups. If this number is greater than
        number_supplied, multiple calls to sec_rgy_pgo_get_members()
        are necessary. Use the member_cursor parameter to coordinate
        successive calls.

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

 DESCRIPTION

 The sec_rgy_pgo_get_members() routine returns a list of the members in
 the specified group or organization, or a list of groups in which a
 specified principal is a member.

 The member_cursor parameter specifies the starting point for the search
 through the registry database.  It provides an automatic place holder
 in the database.  The routine automatically updates member_cursor to
 point to the next member or group (if any) after the returned list.  If
 not all of the members or groups are returned, the updated cursor can
 be supplied on successive calls to return the remainder of the list.

 Permissions Required

 The sec_rgy_pgo_get_members() routine requires the r (read) permission
 on the group, organization, or principal object specified by go_name.

 CAUTIONS

 There are several different types of cursors used in the registry
 Application Programmer Interface (API). Some cursors point to PGO
 items, others point to members in a membership list, and others point
 to account data. Do not use a cursor for one sort of object in a call
 expecting another sort of object. For example, you cannot use the same
 cursor on a call to sec_rgy_acct_get_projlist() and
 sec_rgy_pgo_get_next().  The behavior in this case is undefined.

 Furthermore, cursors are specific to a server. A cursor pointing into
 one replica of the registry database is useless as a pointer into
 another replica.

 Use sec_rgy_cursor_reset() to renew a cursor for use with another call
 or for another server.

 RETURN VALUES

 The routine returns:

  +  The names of the groups or members in member_list[]

  +  The number of members or groups returned by the call in
     number_supplied

  +  The total number of members in the group or organization, or the
     total number of groups in which the principal is a member in
     number_members

 FILES

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

 ERRORS

 sec_rgy_no_more_entries
              The cursor points to the end of the membership list for
              a group or organization or to the end of the list of
              groups for a principal.

 sec_rgy_object_not_found
              The specified group, organization, or principal could
              not be found.

 sec_rgy_server_unavailable
              The DCE Registry Server is unavailable.

 error_status_ok
              The call was successful.

 RELATED INFORMATION

 Functions: sec_intro
            sec_rgy_pgo_add_member
            sec_rgy_cursor_reset
            sec_rgy_pgo_is_member
            sec_rgy_acct_get_proj