FLAP Messages
This section describes the format and contents of FLAP messages. FLAP messages are XML fragments that use namespaces in XML (see Reference 4) to provide extensibility for both technologies and vendors.
Schema UML
The UML notation for the base schema is shown in Figure A.1. This diagram displays the relationships between the types used in this section.
Figure A.1: A high-level message schema UML.
Core Message Definitions
The core FLAP message types are the Notification, Resynchronization, Resynchronization Response, Access Query, and Access Query Response messages. The core message types are composed into a substitution group named_message.
The Notification Message
The LIS or ALE sends a Notification message to inform the other that the access conditions of a particular terminal have changed. Table A.2 shows the components of the Notification message.
| Name | Type | # | Description |
|---|---|---|---|
| ale | Attribute (ipAddress) | 0‥1 | This attribute identifies the ALE that has provided this information to the LIS. This attribute should be provided by the LIS where it is notifying an ALE that another ALE has provided the access information. |
| terminal | Element (terminalType) | 1 | This element identifies the terminal. |
| access | Element (accessType) | 1 | This element provides information about the terminal's physical network access. |
The Resynchronization Message
The Resynchronization message is sent by the LIS to request that the ALE provide information on all terminals that have changed access conditions in a given time period. The time period is specified as the time from the given time to the present.
The ALE must respond to the Re-synchronization message in a timely manner. Table A.3 shows the components of the Re-synchronization message.
| Name | Type | # | Description |
|---|---|---|---|
| since | Attribute (dateTime) | 0‥1 | This attribute specifies the start time for the period. The period ends at the time the request is received. The ALE must be able to deal with a value in the future, as this message may be used for a connection "keep-alive" mechanism. |
The Resynchronization Response Message
The Re-synchronization Response message is sent by the ALE in response to a Re-synchronization message. The contents of the Re-synchronization Response are similar to the Notification, except that an empty Re-synchronization Response is sent if no changes have occurred during the requested interval.
If the since attribute is specified, the ALE must provide information on terminals that have left the network, including an empty access element. If the since attribute is omitted from the Re-synchronization message, the Resynchronization Response messages sent in reply may omit information for terminals that are not currently within the network monitored by the ALE.
The Resynchronization Response must include terminal and access information when there have been changes in the monitored network. If no changes have occurred, the response shall be a BEEP NUL message with no content.
Table A.4 shows the components of the Resynchronization Response message.
| Name | Type | # | Description |
|---|---|---|---|
| result | Attribute (resultCodeType) | 1 | This attribute contains a code indicating the result type for this message. |
| terminal | Element (terminalType) | 1 | This element identifies the terminal. |
| access | Element (accessType) | 1 | This element provides information about the terminal's physical network access. |
The Access Query Message
The Access Query message is used by the LIS to request information from the ALE.
The ALE must respond to the Access Query in a timely manner. Table A.5 shows the components of an Access Query message.
| Name | Type | # | Description |
|---|---|---|---|
| exact | Attribute (boolean) | 0‥1 | If present and set to true, the ALE must send only one response. If set to true, the terminal identification, optionally excluding vendor extensions, at the ALE must be identical to that specified by the LIS, that is, no partial matches are allowed. |
| terminal | Element (terminalType) | 1 | This element identifies the terminal. |
| access | Element (accessType) | 1 | This element provides information about the terminal's physical network access. |
The Access Query Response Message
The Access Query Response message is sent by the ALE in response to an Access Query message from the LIS. Table A.6 shows the components of the Access Query Response message.
| Name | Type | # | Description |
|---|---|---|---|
| result | Attribute (resultCodeType) | 1 | This attribute contains a code indicating the result type for this message. |
| terminal | Element (terminalType) | 0‥1 | This element optionally identifies the terminal. This should be used where the identification information provided by the LIS in the Access Query was incomplete or inaccurate. |
| access | Element (accessType) | 0‥1 | This element provides information about the terminal's physical network access. This element is omitted if a failure result is indicated. |
Management Message Definitions
Management messages can be used by either LIS or ALE outside of core FLAP messaging. These messages establish namespace prefix bindings, indicate error conditions, and provide feedback.
Namespace Declaration Type Definition
To avoid having to include a number of namespace prefix attributes in every request (using the xmlns attribute), FLAP includes the ns-prefix message. The ns-prefix message establishes a context for all messages that follow it in the channel. Namespace prefixes declared by the ns-prefix message must be considered in scope when evaluating all subsequent messages.
The ns-prefix message may be sent in the start message.
The ns-prefix message must always include the FLAP namespace. It is recommended that either the FLAP namespace or the namespace of a technology extension be the default namespace.
The ns-prefix message permits any content in order to enable schema validation by insertion. In this method, the ns-prefix element is taken as the document element for all messages; each message is inserted into the ns-prefix element before validation. This ensures that the namespace prefixes defined on the ns-prefix are in scope for each message.
Error Indication
An error indication is sent when the converse stream contains an error or there is a failure in the node that is not related to any specific message. Error indications may be used for XML parsing errors, administrative actions, congestion, or as necessary.
The error indication is not a part of the _message substitution group, so it does not contain the common elements described in the later section "Result Codes." Table A.7 shows the components that form the error indication.
| Name | Type | # | Description |
|---|---|---|---|
| cause | Attribute (resultCodeType) | 1 | This attribute indicates the reason for the error. |
| xml:lang | Attribute (language) | 0‥1 | This attribute specifies the language (and character set) of the content text. |
| {content} | Text (0‥256 characters) | 0‥1 | The error element may contain human-readable text describing the error condition in more detail. |
Common Type Definitions
Terminal Identification Type
Terminal identification is dependent on the type of access technology used. Therefore, the terminal type defined does not require any specific content.
Access Information Type
Information about the access characteristics of a terminal is also dependent on the specific access technology employed.
The access element is defined to include two attributes that specify the time period over which this information is valid.
For a Notification or Resynchronization Response message, the access information may be left empty to indicate that a terminal has left the domain managed by the ALE. In this case, the time attribute should be set to the time at which the ALE detects the change; the expires attribute should not be set, unless it contains an identical value to time.
Table A.8 describes the time attributes associated with access information.
| Name | Type | # | Description |
|---|---|---|---|
| time | Attribute (dateTime) | 1 | The time at which the access information was determined. |
| expires | Attribute (dateTime) | 0‥1 | The time beyond which the information must not be used. This attribute may be omitted where this information cannot be determined. Note also that this is the latest time only; access information might become incorrect before this time. |
IP Address
The only element definition defined for FLAP is the IP Address element, ip. This type is included for use in technology extensions either directly, or through use of the ipAddress type.
Result Codes
Result codes are defined to use the same three-digit scheme as applied by FTP, HTTP, and SIP (among others) (see Reference 5). In this scheme, the first digit indicates the general type of the message, while the second and third digits are specific. Table A.9 enumerates the meaning of common result codes.
| Code | Short Description | Usage Notes |
|---|---|---|
| 200 | Success | Indicates success. |
| 201 | Terminal left | Used for a notification or resynchronization response that indicates that the terminal has left the domain monitored by the ALE. |
| 400 | Badly formed XML | The stream or message, if one can be reliably determined, contained badly formed XML. This includes illegal characters, unbalanced elements, and any errors. Note that while validation is not performed on the contents of the vendor element, badly formed XML may result in an unrecoverable parsing error. Parsers should attempt to ignore errors within vendor elements. |
| 401 | XML validation failure | The stream or message, if one can be reliably determined, contained validation errors against the schema. Note that validation is not required for the contents of the vendor element by definition. Therefore, although implementations may choose validate vendor extensions, validation errors must not be generated for such errors. |
| 402 | Unsupported encoding | The encoding used by the end stream is not supported. |
| 403 | Unknown namespace prefix | A namespace prefix was used, but the namespace binding was not established with the last ns-prefix message. |
| 404 | Unknown message type | The request type is not known. |
| 405 | Technology not supported | The access technology indicated in the request is not supported by the ALE. |
| 406 | Insufficient identification | This result code indicates that the terminal identification provided did not include sufficient information to uniquely identify a single terminal. |
| 407 | Conflicting identification | This result code indicates that the terminal identification resulted in a possible match for more than one terminal. This code is used where the terminal identification provided was not sufficient to uniquely identify a single terminal. For example, this result code applies if the request provided mismatched IP and hardware addresses for an Ethernet host. |
| 408 | Terminal not found | This result code indicates that the terminal indicated in a request could not be found. |
| 409 | Inadequate history for resynchronization | This result code indicates that the ALE was unable to provide resynchronization information for the entire period requested. This error is provided in response to a Resynchronization request with the since parameter. |
| 410 | Unsupported operation | The request type is not supported. |
| 500 | Unknown error | The type of error could not be determined. |
| 501 | Unspecified error | The type of error is known, but no code exists to describe it. |
| 502 | Administrative action in progress | A request could not be processed due to an administrative action. |
| 503 | Processing overload | A request could not be processed due to congestion. This code may also be sent to indicate a general level of congestion. |
| 504 | Network error | A request could not be completed due to network connectivity failure, or lack of response to a network request. This message may be sent to indicate that requests may fail due to a network outage. |
EAN: 2147483647
Pages: 129