NAME

fn_ctx_list_names, FN_namelist_t, fn_namelist_next, fn_namelist_destroy - list the atomic names bound in a context

SYNOPSIS

cc [ flag . . . ] file . . . -lxfn [ library . . . ]

#include <xfn/xfn.h>
FN_namelist_t * fn_ctx_list_names(FN_ctx_t* ctx, const FN_composite_name_t * name,
     FN_status_t * status);
FN_string_t * fn_namelist_next(FN_namelist_t* nl, FN_status_t * status);
void fn_namelist_destroy(FN_namelist_t * nl, FN_status_t * status);

MT-LEVEL

Safe.

DESCRIPTION

This set of operations is used to list the names bound in the target context named name relative to the context ctx . Note that name must name a context. If the intent is to list the contents of ctx, name should be an empty composite name.

The call to fn_ctx_list_names( ) initiates the enumeration process. It returns a handle to an FN_namelist_t object that can be used to enumerate the names in the target context.

The operation fn_namelist_next( ) returns the next name in the enumeration identified by nl and updates nl to indicate the state of the enumeration. Successive calls to fn_namelist_next( ) using nl return successive names in the enumeration and further update the state of the enumeration. fn_namelist_next( ) returns a NULL pointer when the enumeration has been completed.

fn_namelist_destroy( ) is used to release resources used during the enumeration. This may be invoked at any time to terminate the enumeration.

RETURN VALUE

fn_ctx_list_names( ) returns a pointer to an FN_namelist_t object if the enumeration is successfully initiated; otherwise it returns a NULL pointer.

fn_namelist_next( ) returns a NULL pointer if no more names can be returned in the enumeration.

In the case of a failure, these operations return in status a code indicating the nature of the failure.

ERRORS

Each successful call to fn_namelist_next( ) returns a name and sets status to FN_SUCCESS.

When fn_namelist_next( ) returns a NULL pointer, it indicates that no more names can be returned. status is set in the following way:

FN_SUCCESS

The enumeration has completed successfully.

FN_E_INVALID_ENUM_HANDLE

The supplied enumeration handle is not valid. Possible reasons could be that the handle was from another enumeration, or the context being enumerated no

longer accepts the handle (due to such events as handle expiration or updates to the context).

FN_E_PARTIAL_RESULT

The enumeration is not yet complete but cannot be continued.

Other status codes, such as FN_E_COMMUNICATION_FAILURE, are also possible in calls to fn_ctx_list_names( ), fn_namelist_next( ) and fn_namelist_destroy( ). These functions set status for these other status codes as described in FN_status_t(3N) and xfn_status_codes(3N).

EXAMPLE

The following code fragment illustrates a how the list names operations may be used. extern FN_string_t * user_input;

FN_ctx_t * ctx;

FN_composite_name_t * target_name= fn_composite_name_from_string(user_input); FN_status_t * status= fn_status_create();

FN_string_t * name;

FN_namelist_t * nl;

ctx = fn_ctx_handle_from_initial(status);

/* error checking on 'status' * /

if ((nl=fn_ctx_list_names(ctx, target_name, status)) == 0) {

/* report 'status' and exit * /

}

while (name=fn_namelist_next(nl, status)) {

/* do something with 'name' * /

fn_string_destroy(name);

}

/* check 'status' for reason for end of enumeration and report if necessary * /

/* clean up * /

fn_namelist_destroy(nl, status);

/* report 'status' * /

APPLICATION USAGE

The names enumerated using fn_namelist_next( ) are not ordered in any way. There is no guaranteed relation between the order in which names are added to a context and the order of names obtained by enumeration. The specification does not guarantee that any two series of enumerations will return the names in the same order.

When a name is added to or removed from a context, this may or may not invalidate the enumeration handle that the client holds for that context. If the enumeration handle becomes invalid, the status code FN_E_INVALID_ENUM_HANDLE is returned in status. If the enumeration handle remains valid, the update may or may not be visible to the client.

In addition, there may be a relationship between the ctx argument supplied to fn_ctx_list_names( ) and the FN_namelist_t object it returns. For example, some implementations may store the context handle ctx within the FN_namelist_t object for subsequent fn_namelist_next( ) calls. In general, a fn_ctx_handle_destroy( ) should not be invoked on ctx until the enumeration has terminated.

SEE ALSO

FN_composite_name_t(3N), FN_ctx_t(3N), FN_status_t(3N), FN_string_t(3N), fn_ctx_handle_destroy(3N), xfn_status_codes(3N), xfn (3N)