NAME¶
VistaIOExtractAttr - fetch and delete an attribute
SYNOPSIS¶
VistaIOBoolean VistaIOExtractAttr ( list, name, dict, repn, value, required)
VistaIOAttrList list;
VistaIOStringConst name;
VistaIODictEntry * dict;
VistaIORepnKind repn;
VistaIOPointer value;
VistaIOBoolean required;
ARGUMENTS¶
- list
- Specifies the list of attributes to be searched by name for the desired
attribute.
- name
- Specifies the name of the desired attribute.
- dict
- May specify a dictionary to be used in recognizing a keyword stored as the
attribute's value, or it may be NULL
- repn
- Specifies the representation in which the attribute value is to be
returned.
- value
- Specifies a location at which the attribute value is be returned.
- required
- Is TRUE if failure to find the attribute should be
considered an error.
DESCRIPTION¶
VistaIOExtractAttr locates the first attribute named
name in
list, removing it if found and returning its value.
If a dictionary,
dict, has been provided and the attribute's value is
stored as a character string, the routine determines whether the string is a
keyword defined in the dictionary. If so, it uses the value associated with
that keyword rather than the attribute's original value. (See the
VistaIOdictionary(3) manual page.)
The value obtained directly from the attribute, or indirectly via the
dictionary, is converted to the representation
repn and then stored at
the location pointed to by
value. The
repn argument may have any
VistaIORepnKind value or any of the values returned by
VistaIORegisterType(3). However, an attribute value that is a string
can only be returned as a string or a number, and other attribute values can
only be returned in the representation with which they are stored. (The
VistaIOGetAttrRepn(3) macro can be used to determine an attribute
value's representation.)
RETURN VALUES¶
VistaIOExtractAttr returns
FALSE if
required
is
TRUE and no attribute named
name is found. If
also returns
FALSE if an attribute is found but its
value cannot be converted to the desired representation. Otherwise,
VistaIOExtractAttr returns
TRUE while perhaps
modifying the list
list and storing a value at
value.
SEE ALSO¶
VistaIOGetAttr(3),
VistaIOGetAttrValue(3),
VistaIOLookupAttr(3),
VistaIODeleteAttr(3),
VistaIOInsertAttr(3),
VistaIOattribute(3),
VistaIOdictionary(3),
NOTES¶
VistaIOExtractAttr is meant for use with attribute lists representing
sets, in which each attribute name occurs at most once. If
list
contains multiple attributes named
name, only the first is located.
The
value argument must point to sufficient storage to contain a value of
the representation requested. Neither the routine nor the C compiler can
automatically check that this is so.
If a string value is returned, it will be in newly-allocated storage. Release
the storage with
VistaIOFree(3) when done with the string.
DIAGNOSTICS¶
- ``name attribute missing.''
- No attribute named name could be found, and required is
TRUE
- ``name attribute has bad value.''
- The attribute was found, but its value cannot be converted to the desired
representation.
AUTHOR¶
Art Pope <pope@cs.ubc.ca>
Adaption to vistaio: Gert Wollny <gw.fossdev@gmail.com>