PreviousNext

sec_rgy_acct_get_projlist(3sec)

Returns the projects in an account's project list

Synopsis

#include <dce/acct.h>

void sec_rgy_acct_get_projlist(
sec_rgy_handle_t context,
sec_rgy_login_name_t *login_name,
sec_rgy_cursor_t *projlist_cursor,
signed32 max_number,
signed32 *supplied_number,
uuid_t id_projlist[ ],
signed32 unix_projlist[ ],
signed32 *num_projects,
error_status_t *status);

Parameters

Input

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

login_name
A pointer to the account login name. A login name is composed of three character strings, containing the principal, group, and organization (PGO) names corresponding to the account.

For the group and organization names, blank strings can serve as wildcards, matching any entry. The principal name must be input.

max_number
The maximum number of projects to be returned by the call. This must be no larger than the allocated size of the projlist[ ] arrays.

Input/Output

projlist_cursor
An opaque pointer indicating a specific project in an account's project list. The sec_rgy_acct_get_projlist( ) routine returns the project indicated by projlist_cursor, and advances the cursor to point to the next project in the list. When the end of the list is reached, the routine returns the value sec_rgy_no_more_entries in the status parameter. Use sec_rgy_cursor_reset( ) to reset the cursor.

Output

supplied_number
A pointer to the actual number of projects returned. This will always be less than or equal to the max_number supplied on input. If there are more projects in the account list, sec_rgy_acct_get_projlist( ) sets projlist_cursor to point to the next entry after the last one in the returned list.

id_projlist[ ]
An array to receive the UUID of each project returned. The size allocated for the array is given by max_number. If this value is less than the total number of projects in the account project list, multiple calls must be made to return all of the projects.

unix_projlist[ ]
An array to receive the UNIX number of each project returned. The size allocated for the array is given by max_number. If this value is less than the total number of projects in the account project list, multiple calls must be made to return all of the projects.

num_projects
A pointer indicating the total number of projects in the specified account's project list.

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

Description
The sec_rgy_acct_get_projlist( ) routine returns members of the project list for the specified account. It returns the project information in two arrays. The id_projlist[ ] array contains the UUIDs for the returned projects. The unix_projlist[ ] array contains the UNIX numbers for the returned projects.

The project list cursor, projlist_cursor, provides an automatic place holder in the project list. The sec_rgy_acct_get_projlist( ) routine automatically updates this variable to point to the next project in the project list. To return an entire project list, reset projlist_cursor with sec_rgy_cursor_reset( ) on the initial call and then issue successive calls until all the projects are returned.

Permissions Required
The sec_rgy_acct_get_projlist( ) routine requires the r (read) permission on the account principal for which the project list data is to be returned.

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 refresh a cursor for use with another call or for another server.

Files

/usr/include/dce/acct.idl
The idl file from which dce/acct.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 is at the end of the list of projects.

sec_rgy_not_authorized
The client program is not authorized to see a project list for this principal.

sec_rgy_object exists
The account to be added already exists.

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

sec_rgy_pgo_get_next(3sec)