sec_rgy_pgo_get_members(3sec)

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. For groups, fully qualified names are returned for foreign principals and local names for local principals. (Only local principals can be members of an organization.)

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

/usr/include/dce/pgo.idl
The idl file from which dce/pgo.h was derived.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

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(3sec)

sec_rgy_pgo_add_member(3sec)

sec_rgy_cursor_reset(3sec)

sec_rgy_pgo_is_member(3sec)

sec_rgy_acct_get_projlist(3sec)