The Base Context Interface

This section describes the operations in the base context interface. The interfaces to the objects used in the operations are described in Parameters Used in the Interface.

• Names in Context Operations

• Requirements for Supporting the Context Operations

• Status Objects

• Getting Context Handles

• Lookup and List Contexts

• Updating Bindings

• Managing Contexts

Names in Context Operations

In most of the operations of the base context interface, the caller supplies a context and a composite name argument. The supplied composite name is always interpreted relative to the supplied context.

The operation might eventually be effected on a different context called the operation's target context. Each operation has an initial resolution phase that conveys the operation to its target context, following which the operation is applied. The effect (but not necessarily the implementation) is that of:

• Doing a lookup on that portion of the name that represents the target context

• Invoking the operation on the target context

The contexts involved only in the resolution phase are called intermediate contexts. Normal resolution of names in context operations always follows XFN links, which are defined in XFN Links.

Requirements for Supporting the Context Operations

The lookup operation fn_ctx_lookup() must be supported by all contexts. When contexts do not support other operations, they can return an FN_E_OPERATION_NOT_SUPPORTED status code (see codes in Table 2–3).

XFN contexts are required to support the resolution phase of every operation in the base context and attribute interface when involved in the operation as intermediate contexts. That is, each intermediate context must participate in the process of conveying the operation to the target context, even if it does not support that operation itself. For example, not all contexts need to allow binding and listing names. However, all contexts must fully support the resolution phase of these operations.

Composite names are passed to an XFN context implementation in a structural form as an ordered sequence of components. When resolving a name, the context implementation is responsible for:

• Determining which set of leading components it must resolve

• Resolving that portion to a reference

• Returning a status object containing this reference and the portion of the name unresolved

Composite name resolution is further discussed in Composite Name Resolution.

Status Objects

In each context operation, the caller supplies an FN_status_t parameter. The called function sets this status object as described in Status Objects and Status Codes. All status objects are handled in this way for each operation in the base context interface (this is not restated in the individual operation descriptions).

Getting Context Handles

All operations on a context require a context handle. There are several ways of obtaining a context handle. If you have a reference, you can use it to construct a context handle. Otherwise, to get a handle to the initial context, you must call fn_ctx_handle_from_initial().

fn_ctx_handle_from_initial
fn_ctx_handle_from_ref

Construct Handle to Initial Context

This operation returns a handle to the callers initial context. On successful return, the context handle points to a context containing the bindings described in Initial Context Bindings.

FN_ctx_t *fn_ctx_handle_from_initial(
    unsigned int authoritative,
    FN_status_t *status);

authoritative specifies whether the handle to the Initial Context returned should be authoritative, with respect to information the context obtains from the naming service. When the flag is non-zero, subsequent operations on this context handle can access the most authoritative information. When authoritative is zero, the handle to the Initial Context returned need not be authoritative. Authoritativeness is determined by specific naming services. In some, the authoritative source is a single “master” servers, while in others, the authoritative source is a quorum of servers.

Construct Context Handle From Reference

This operation returns a handle to an FN_ctx_t object given a reference, ref, for that context.

FN_ctx_t *fn_ctx_handle_from_ref(
    const   FN_ref_t *ref, 
    unsigned int authoritative,
    FN_status_t *status);      

authoritative specifies whether the handle to the context returned should be authoritative, with respect to information the context obtains from the naming service. When the flag is non-zero, subsequent operations on this context handle can access the most authoritative information. When authoritative is zero, the handle to the context returned need not be authoritative. Authoritativeness is determined by specific naming services. In some, the authoritative source is a single “master” server, while in others, the authoritative source is a quorum of servers.

Lookup and List Contexts

fn_ctx_lookup
fn_ctx_list_names
fn_namelist_next
fn_namelist_destroy
fn_ctx_list_bindings
fn_bindinglist_next
fn_bindlist_destroy
fn_ctx_lookup_link

Lookup

This operation returns the reference bound to name relative to the context ctx.

FN_ref_t *fn_ctx_lookup(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);

List Names

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

FN_nameslist_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);

The call to fn_ctx_list_names() initiates the enumeration process for the target context. It returns an FN_nameslist_t object that you can use for the enumeration.

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 marker. Successive calls to fn_namelist_next() using nl return successive names 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 call can be invoked at any time to terminate the enumeration.

The names enumerated using the list names operations are not in any order. There is no guaranteed relation between the order in which names are added to a context and the order in which names are obtained by enumeration. There is no guarantee that any two enumerations will return the names in the same order.

When a name is added to or removed from the context, this might not necessarily invalidate the enumeration handle that the client holds for that context. If the enumeration handle remains valid, the update might or might not be visible to the client.

List Bindings

This set of operations is used to list the set of names and bindings in the context named by name, relative to the context ctx. The name must name a context. If the intent is to list the contents of ctx, name should be an empty composite name.

FN_bindinglist_t* fn_ctx_list_bindings(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);FN_string_t *fn_bindinglist_next(
FN_bindinglist_t *bl,
    FN_ref_t ** ref,
    FN_status_t *status);
void fn_bindinglist_destroy(
   FN_bindinglist_t *bl);

The semantics of these operations are similar to those for listing names. In addition to a name string being returned, fn_bindinglist_next() also returns the reference of the binding for each member of the enumeration.

Lookup Link

This operation returns the XFN link bound to name. The terminal atomic part of name must be bound to an XFN link.

FN_ref_t *fn_ctx_lookup_link(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);

The normal fn_ctx_lookup() operation follows all XFN links encountered, including any that are bound to the terminal atomic part of name. This operation differs from the normal lookup in that when the terminal atomic part of name is an XFN link, this last link is not followed, and the operation returns the link.

Updating Bindings

fn_ctx_bind
fn_ctx_unbind
fn_ctx_rename

Bindings can be added, overwritten, removed, or renamed.

Bind

This operation binds the supplied reference ref to the supplied composite name name, taken relative to ctx. The binding is made in the target context—that named by all but the terminal atomic part of name. The operation binds the terminal atomic name to the supplied reference in the target context. The target context must already exist.

int fn_ctx_bind(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    const   FN_ref_t *ref,
    unsigned int exclusive,
    FN_status_t *status);

The value of exclusive determines what happens if the terminal atomic part of the name is already bound in the target context. If exclusive is nonzero and name is already bound, the operation fails. If exclusive is zero, the new binding replaces any existing binding.

The value of ref cannot be NULL. If you want to reserve a name using the fn_ctx_bind() operation, bind a reference containing no address. This reference can be naming service-specific or it can be the conventional NULL reference.

Unbind

This operation removes the terminal atomic name in name from the target context—that named by all but the terminal atomic part of name.

int fn_ctx_unbind(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    FN_status_t *status);

This operation is successful even if the terminal atomic name was not bound in target context, but fails if any of the intermediate names are not bound. fn_ctx_unbind() operations are idempotent.

Rename

This operation binds the reference currently bound to oldname, resolved relative to ctx to newname, and unbinds oldname. The newname is resolved relative to the target context—that named by all but the terminal atomic part of oldname.

int fn_ctx_rename(
    FN_ctx_t *ctx,
    const FN_composite_name_t *oldname,
    const FN_composite_name_t *newname,
    unsigned int exclusive,
    FN_status_t *status);

If exclusive is zero, this operation overwrites any old binding of newname. If exclusive is nonzero, the operation fails if newname is already bound.

The only restriction that XFN places on newname is that it be resolved relative to the target context. For example, in some implementations, newname might be restricted to be a name in the same naming system as the terminal component of oldname. In another implementation, newname might be restricted to an atomic name.

Managing Contexts

fn_ctx_create_subcontext
fn_ctx_destroy_subcontext
fn_ctx_get_ref
fn_ctx_get_syntax_attrs
fn_ctx_handle_destroy
fn_ctx_equivalent_name

Contexts can be created, destroyed,and referenced.

Create Subcontext

This operation creates a new context of the same type as the target context—that named by all but the terminal atomic part of name—and binds it to the composite name name resolved relative to the context ctx, and returns a reference to the newly created context.

FN_ref_t *fn_ctx_create_subcontext(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    FN_status_t *status);

As with the bind operation, the target context must already exist. The new context is created and bound in the target context using the terminal atomic name in name. The operation fails if the terminal atomic name already exists in the target context.

The new subcontext exports the context interface and is created in the same naming system as the target context. XFN does not specify any further properties of the new subcontext. Other properties of the subcontext are determined by the target context and its naming system.

Destroy Subcontext

This operation destroys the subcontext named by name, interpreted relative to ctx, and unbinds the name.

int fn_ctx_destroy_subcontext(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    FN_status_t *status);

As with the unbind operation, the operation succeeds if the terminal atomic name is not bound in the target context—that named by all but the terminal atomic part of name.

Some aspects of this operation are determined by the target context and its naming system. For example, XFN does not specify what happens if the named subcontext is not empty when the operation is invoked.

Get Reference to Context

This operation returns a reference to the supplied context object.

FN_ref_t *fn_ctx_get_ref(
    const FN_ctx_t *ctx,
    FN_status_t *status);

Get Syntax Attributes of Context

This operation returns the syntax attributes associated with the context named by name, relative to the context ctx.

FN_attrset_t *fn_ctx_get_syntax_attrs(
    FN_ctx_t *ctx,
    const   FN_composite_name_t *name,
    FN_status_t *status);

This operation is different from other XFN attribute operations in that these syntax attributes could be obtained directly from the context. Attributes obtained through other XFN attribute operations might not be associated with the context; they might be associated with the reference of the context, rather than with the context itself (see Relationship to Naming Operations).

Destroy Context Handler

This operation destroys the context handle ctx and allows the implementation to free resources associated with the context handle. This operation does not affect the state of the context itself.

void fn_ctx_handle_destroy(FN_ctx_t *ctx);

Construct an Equivalent Name (Preliminary Specification)

Given the name of an object name relative to the context ctx, the operation returns an equivalent name for that object, relative to the same context ctx, that has leading_name as its initial atomic name. Two names are said to be equivalent if they have prefixes that resolve to the same context, and the parts of the names immediately following the prefixes are identical. For example, for user jsmith, the names “myself/service/calendar” is equivalent to “user/jsmith/service/calendar” when resolved relative to the Initial Context.

FN_composite_name_t *fn_ctx_equivalent_name(
    FN_ctx_t *ctx,
    const FN_composite_name_t *name,
    const FN_string_t *leading_name,
    FN_status_t *status);

If an equivalent name cannot be constructed, the value 0 is returned and the status argument set appropriately.