Партнёры:
Хостинг:
NAME
fn_attr_multi_get, FN_multigetlist_t, fn_multigetlist_next,
fn_multigetlist_destroy - return multiple attributes associ-
ated 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);
DESCRIPTION
This set of operations returns one or more attributes asso-
ciated 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 (iden-
tifiers, 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.
RETURN VALUES
fn_attr_multi_get() returns a pointer to an
FN_multigetlist_t object if the enumeration has been ini-
tiated 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.
ERRORS
Each call to fn_multigetlist_next() sets status as follows:
FN_SUCCESS
If an attribute was returned, there are more attri-
butes 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 attri-
bute.
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 accept-
able 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. Pos-
sible 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 han-
dle 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).
USAGE
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 neces-
sarily return attributes identifying those that could not be
read. Implementations are not required to return the attri-
butes in any order.
There may be a relationship between the ctx argument sup-
plied 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 gen-
eral, a fn_ctx_handle_destroy() should not be invoked on ctx
until the enumeration has terminated.
EXAMPLES
Example 1: A sample program displaying how to use
fn_attr_multi_get() function.
The following code fragment illustrates to obtain all attri-
butes 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' */
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
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)
NOTES
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.
|
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |