| |
| XFN Interface Library Functions | fn_attr_multi_get(3XFN) |
| | fn_attr_multi_get, FN_multigetlist_t, fn_multigetlist_next, fn_multigetlist_destroy - return multiple attributes
associated with named object |
SYNOPSIS
| |
cc [ flag ... ] file ... -lxfn [ library ... ]
#include <xfn/xfn.h>
FN_multigetlist_t *fn_attr_multi_get(FN_ctx_t *ctx, const FN_composite_name_t *name, const FN_attrset_t *attr_ids, unsigned int follow_link, FN_status_t *status); |
| | FN_attribute_t *fn_multigetlist_next(FN_multigetlist_t *ml, FN_status_t *status); |
| | void fn_multigetlist_destroy(FN_multigetlist_t *ml, FN_status_t *status); |
| |
This set of operations returns one or more attributes associated with the object named by name relative to the context ctx. If name is empty, the attributes associated with ctx are returned.
The value of follow_link determines what happens when the terminal atomic part of name is bound to an XFN link.
If follow_link is non-zero, such a link is followed, and the values of the attribute associated with the final named object are returned; if follow_link
is zero, such a link is not followed. Any XFN links encountered before the terminal atomic name are always followed.
The attributes returned are those specified in attr_ids. If the value of attr_ids is 0, all attributes associated with the
named object are returned. Any attribute values in attr_ids provided by the caller are ignored; only the attribute identifiers are relevant for this operation. Each attribute
(identifier, syntax, values) is returned one at a time using an enumeration scheme similar to that for listing a context.
fn_attr_multi_get() initiates the enumeration process. It returns a handle to an FN_multigetlist_t object that can be used for the enumeration.
The operation fn_multigetlist_next() returns a new FN_attribute_t object containing the next attribute (identifiers, syntaxes, and values) requested and updates
ml to indicate the state of the enumeration.
The operation fn_multigetlist_destroy() releases the resources used during the enumeration. It may be invoked before the enumeration has completed to terminate the enumeration.
|
| |
fn_attr_multi_get() returns a pointer to an FN_multigetlist_t object if the enumeration has been initiated successfully; a NULL
pointer (0) is returned if it failed.
fn_multigetlist_next() returns a pointer to an FN_attribute_t object if an attribute was returned, a NULL pointer (0)
if no attribute was returned.
In the case of a failure, these operations set status to indicate the nature of the failure.
|
| |
Each call to fn_multigetlist_next() sets status as follows:
-
FN_SUCCESS
- If an attribute was returned, there are more attributes to be enumerated. If
no attribute was returned, the enumeration has completed successfully.
-
FN_E_ATTR_NO_PERMISSION
- The caller did not have permission to read this attribute.
-
FN_E_INSUFFICIENT_RESOURCES
- Insufficient resources are available to return the attribute's values.
-
FN_E_INVALID_ATTR_IDENTIFIER
- This attribute identifier was not in a format acceptable to the naming system, or its contents
was not valid for the format specified for the identifier.
-
FN_E_INVALID_ENUM_HANDLE
- (No attribute should be returned with this status code). The given enumeration handle is not
valid. Possible reasons could be that the handle was from another enumeration, or the object being processed no longer accepts the handle (due to such events as handle expiration or updates to the object's
attribute set).
-
FN_E_NO_SUCH_ATTRIBUTE
- The object did not have an attribute with the given identifier.
-
FN_E_PARTIAL_RESULT
- (No attribute should be returned with this status code). The enumeration is not yet complete but cannot
be continued.
For FN_E_ATTR_NO_PERMISSION, FN_E_INVALID_ATTR_IDENTIFIER, FN_E_INSUFFICIENT_RESOURCES, or FN_E_NO_SUCH_ATTRIBUTE, the returned attribute contains only the attribute identifier (no value or syntax). For these four status codes and FN_SUCCESS (when an attribute was returned), fn_multigetlist_next() can be called again to return another attribute. All other status codes indicate that
no more attributes can be returned by fn_multigetlist_next().
Other status codes, such as FN_E_COMMUNICATION_FAILURE, are also possible, in which case, no attribute is returned. In such cases, status
is set as described in FN_status_t(3XFN) and xfn_status_codes(3XFN).
|
| |
Implementations are not required to return all attributes requested by attr_ids. Some may choose to return only the attributes found successfully, followed by a status of
FN_E_PARTIAL_RESULT; such implementations may not necessarily return attributes identifying those that could not be read. Implementations are not required to return
the attributes in any order.
There may be a relationship between the ctx argument supplied to fn_attr_multi_get() and the FN_multigetlist_t object it returns. For
example, some implementations may store the context handle ctx within the FN_multigetlist_t object for subsequent fn_multigetlist_next()
calls. In general, a fn_ctx_handle_destroy() should not be invoked on ctx until the enumeration has terminated.
|
| | Example 1. A sample program displaying how to use fn_attr_multi_get function.
| |
The following code fragment illustrates to obtain all attributes associated with a given name using the fn_attr_multi_get() operations.
| |
/* list all attributes associated with given name */
extern FN_string_t *input_string;
FN_ctx_t *ctx;
FN_composite_name_t *target_name = fn_composite_name_from_string(input_string);
FN_multigetlist_t *ml;
FN_status_t *status = fn_status_create();
FN_attribute_t *attr;
int done = 0;
ctx = fn_ctx_handle_from_initial(status);
/* error checking on 'status' */
/* attr_ids == 0 indicates all attributes are to be returned */
if ((ml=fn_attr_multi_get(ctx, target_name, 0, status)) == 0) {
/* report 'status' and exit */
}
while ((attr=fn_multigetlist_next(ml, status)) && !done) {
switch (fn_status_code(status)) {
case FN_SUCCESS:
/* do something with 'attr' */
break;
case FN_E_ATTR_NO_PERMISSION:
case FN_E_ATTR_INVALID_ATTR_IDENTIFIER:
case FN_E_NO_SUCH_ATTRIBUTE:
/* report error using identifier in 'attr' */
break;
default:
/* other error handling */
done = 1;
}
if (attr)
fn_attribute_destroy(attr);
}
/* check 'status' for reason for end of enumeration and report if necessary */
/* clean up */
fn_multigetlist_destroy(ml, status);
/* report 'status' */
|
|
|
| |
See attributes(5) for descriptions of the following
attributes:
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
| MT-Level | MT-Safe |
|
| |
FN_attribute_t(3XFN), FN_attrset_t(3XFN), FN_composite_name_t(3XFN), FN_ctx_t(3XFN), FN_identifier_t(3XFN), FN_status_t(3XFN), fn_attr_get(3XFN), fn_ctx_handle_destroy(3XFN), fn_ctx_list_names(3XFN), xfn(3XFN), xfn_attributes(3XFN), xfn_status_codes(3XFN), attributes(5)
|
| |
The implementation of XFN in this Solaris release is based on the X/Open preliminary specification. It is likely that there will be minor changes to these interfaces
to reflect changes in the final version of this specification. The next minor release of Solaris will offer binary compatibility for applications developed using the current interfaces. As the interfaces
evolve toward standardization, it is possible that future releases of Solaris will require minor source code changes to applications that have been developed against the preliminary specification.
|
| |
