DCE_SECURITY, API Routines, sec_rgy_pgo_get_members
*Conan The Librarian (sorry for the slow response - running on an old VAX)
|
VMS Help DCE_SECURITY, API Routines, sec_rgy_pgo_get_members *Conan The Librarian (sorry for the slow response - running on an old VAX) |
|
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
|
|
