NAME

sec_rgy_pgo_get_by_name-Returns the data for a named PGO item

SYNOPSIS

#include <dce/pgo.h>

void sec_rgy_pgo_get_by_name(
    sec_rgy_handle_t context,
    sec_rgy_domain_t name_domain,
    sec_rgy_name_t pgo_name,
    sec_rgy_cursor_t *item_cursor,
    sec_rgy_pgo_item_t *pgo_item,
    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.

name_domain

This variable identifies the type of the principal, group, or organization (PGO) item identified by the given name. The valid values are as follows:

sec_rgy_domain_person

The name identifies a principal.

sec_rgy_domain_group

The name identifies a group.

sec_rgy_domain_org

The name identifies an organization.

pgo_name

A character string (type sec_rgy_name_t) containing the name of the principal, group, or organization to search for.

Input/Output

item_cursor

An opaque pointer indicating a specific PGO item entry in the registry database. The sec_rgy_pgo_get_by_name() routine returns the PGO item indicated by item_cursor, and advances the cursor to point to the next item in the database. When the end of the list of entries 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

pgo_item

A pointer to a sec_rgy_pgo_item_t structure to receive the data for the returned PGO item. The data in this structure includes the PGO item's name, UUID, UNIX number (if any), and administrative data, such as whether the item, if a principal, may have a concurrent group set.

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_pgo_get_by_name() routine returns the data for a named PGO item from the registry database. The desired item is identified by its type (name_domain) and name.

The item_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 this variable to point to the next PGO item after the returned item. The returned cursor location can be supplied on a subsequent database access call that also uses a PGO item cursor.

Permissions Required

The sec_rgy_pgo_get_by_name() routine requires the r (read) permission on the PGO item to be viewed.

CAUTIONS

There are several different types of cursors used in the registry 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.

FILES

/usr/include/dce/pgo.idl

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

ERRORS

error_status_ok

The call was successful.

sec_rgy_no_more_entries

The cursor is at the end of the list of PGO items.

sec_rgy_object_not_found

The specified PGO item was not found.

sec_rgy_server_unavailable

The DCE Registry Server is unavailable.

SEE ALSO

Functions: sec_rgy_pgo_add(), sec_rgy_pgo_get_by_id(), sec_rgy_pgo_get_by_unix_num(), sec_rgy_pgo_get_next(), sec_rgy_pgo_id_to_name(), sec_rgy_pgo_id_to_unix_num(), sec_rgy_pgo_name_to_id(), sec_rgy_pgo_unix_num_to_id(), sec_rgy_cursor_reset().