Federated Naming Service Programming Guide

Status Objects and Status Codes

The result statuses of operations in the context interface and the attribute interface are encapsulated in FN_status_t objects. The FN_status_t object contains information about how the operation completed: whether an error occurred in performing the operation, the nature of the error, and information that helps locate where the error occurred. If the error occurred while resolving an XFN link, the status object contains additional information about that error.

The status object contains several items of information as shown in Table 2–2.

Table 2–2 Status Object

Information Type 

Description 

Primary status code

An unsigned int code describing the disposition of the operation.

Resolved name 

In the case of a failure during the resolution phase of the operation, this is the leading portion of the name that was resolved successfully. Resolution might have been successful beyond this point, but the error can not be pinpointed further. 

Resolved reference 

The reference to which the resolved name is bound. 

Remaining name 

The remaining unresolved portion of the name. 

Diagnostic message 

Any diagnostic message returned by the context implementation. 

Link status code

If an error occurs while resolving an XFN link, the primary status code has the value FN_E_LINK_ERROR, and this code describes the error that occurred while resolving the XFN link.

Resolved link name 

In the case of a link error, this contains the resolved portion of the name in the XFN link. 

Resolved link reference 

In the case of a link error, this contains the reference to which the resolved link name is bound. 

Remaining link name 

In the case of a link error, this contains the remaining resolved portion of the name in the XFN link.  

Link diagnostic message 

Any diagnostic message related to the resolution of the link. 

Both the primary status code and the link status code are values of type unsigned int that are drawn from the same set of meaningful values. XFN reserves the values 0 through 127 for standard meanings. Currently, values and interpretations for the codes in Table 2–3 are determined by XFN.

Table 2–3 Status Codes

Code  

Meaning 

FN_SUCCESS

The operation succeeded. 

FN_E_ATTR_IN_USE

When an attribute is being modified using the operation FN_ATTR_OP_ADD_EXCLUSIVE and an attribute with the same identifier already exists, the operation fails with FN_E_ATTR_IN_USE.

FN_E_ATTR_NO_PERMISSION

The caller did not have permission to perform the attempted attribute operation. 

FN_E_ATTR_VALUE_REQUIRED

The operation attempted to create an attribute without a value, and the specific naming system does not allow this. 

FN_E_AUTHENTICATION_FAILURE

The identity of the client principal could not be verified. 

FN_E_COMMUNICATION_FAILURE

An error occurred in communicating with one of the contexts involved in the operation. 

FN_E_CONFIGURATION_ERROR

A problem was detected that indicated an error in the installation of the XFN interfaces.  

FN_E_CONTINUE

The operation should be continued using the remaining name and the resolved reference returned in the status. 

FN_E_CTX_NO_PERMISSION

The client did not have permission to perform the operation. 

FN_E_CTX_NOT_EMPTY

Applies only to fn_ctx_destroy_subcontext(). The naming system required that the context be empty before its destruction, and it was not empty.

FN_E_CTX_UNAVAILABLE

Service could not be obtained from one of the contexts involved in the operation. This might be because the naming system is busy or is not providing service. In some implementations this might not be distinguished from a communication failure. 

FN_E_ILLEGAL_NAME

The name supplied to the operation was not a well-formed composite name, or one of the component names was not well formed according to the syntax of the naming systems involved in its resolution. 

FN_E_INCOMPATIBLE_CODE_SETS

The operation involved character strings of incompatible code sets or the supplied code set is not supported by the implementation. 

FN_E_INCOMPATIBLE_LOCALES

The operation involved character strings of incompatible language or territory locale information, or the specified locale is not supported by the implementation. 

FN_E_INSUFFICIENT_RESOURCES

Either the client or one of the involved contexts could not obtain sufficient resources (on memory, file descriptors, communication ports, stable media space, for example) to complete the operation successfully. 

FN_E_INVALID_ATTR_IDENTIFIER

The attribute identifier was not in a format acceptable to the naming system, or its contents were not valid for the format specified for the identifier. 

FN_E_INVALID_ATTR_VALUE

One of the values supplied was not in the appropriate form for the given attribute. 

FN_E_INVALID_ENUM_HANDLE

The enumeration handle supplied was invalid, either because it was from another enumeration, because an update operation occurred during the enumeration, or for some other reason. 

FN_E_INVALID_SYNTAX_ATTRS

The syntax attributes supplied are invalid or insufficient to fully specify the syntax. 

FN_E_LINK_ERROR

An error occurred while resolving an XFN link encountered during resolution of the supplied name. 

FN_E_LINK_LOOP_LIMIT

A nonterminating loop (cycle) in the resolution is suspected. This arises due to XFN links encountered during the resolution of a supplied composite name. This code indicates either the definite detection of such a cycle, or that resolution exceeded an implementation-defined limit on the number of XFN links allowed for a single operation invoked by the caller (and thus a cycle is suspected). 

FN_E_MALFORMED_LINK

A malformed link reference was encountered. For fn_ctx_lookup_link(), the name supplied resolved to a reference that was not a link.

FN_E_MALFORMED_REFERENCE

A context object could not be constructed from the supplied reference because the reference was not properly formed. 

FN_E_NAME_IN_USE

(Only for operations that bind names.) The supplied name was already in use. 

FN_E_NAME_NOT_FOUND

Resolution of the supplied composite name proceeded to a context in which the next atomic component of the name was not bound. 

FN_E_NO_EQUIVALENT_NAME

No equivalent name can be constructed, either because there is no meaningful equivalence between name and leading_name, or the system does not support constructing the requested equivalent name, for implementation-specific reasons.

FN_E_NO_SUCH_ATTRIBUTE

The object does not have an attribute with the given identifier. 

FN_E_NO_SUPPORTED_ADDRESS

A context object could not be constructed from a particular reference. The reference contained no address type over which the context interface was supported. 

FN_E_NOT_A_CONTEXT

Either one of the intermediate atomic names did not name a context, and resolution could not proceed beyond this point, or the operation required that the caller supply the name of a context, and the name did not resolve to a reference for a context. 

FN_E_OPERATION_NOT_SUPPORTED

The operation attempted is not supported. 

FN_E_PARTIAL_RESULT

The operation attempted is returning a partial result. 

FN_E_SEARCH_INVALID_FILTER

The filter expression had a syntax error or some other problem. 

FN_E_SEARCH_INVALID_OP

An operator in the filter expression is not supported or, if the operator is an extended operator, the number of types of arguments supplied does not match the signature of the operation. 

FN_E_SEARCH_INVALID_OPTION

A supplied search control option could not be supported. 

FN_E_SYNTAX_NOT_SUPPORTED

The syntax type specified is not supported. 

FN_E_TOO_MANY_ATTR_VALUES

The operation attempted to associate more values with an attribute than the naming system supported. 

FN_E_UNSPECIFIED_ERROR

An error occurred that could not be classified by any of the other error codes.