|
|
| Line 1: |
Line 1: |
| {{Protocols/OSCAR}} | | {{Protocols/OSCAR}} |
| FLAP notes from another
| |
| <!--
| |
| Everything in the AIM protocol is embodied in AIM commands. The division is not of packets because more than one command may be sent in any one packet, depending on the transmit timing, etc. Commands are an abstraction above packets, and leads to the definition of the FLAP protocol below.
| |
|
| |
|
| Below is an attempt to generalize the layout of all AIM commands. The acronyms used are those used by the AIM client and the AIM divison of AOL as defined in the document at http://www.aim.aol.com/javadev/terminology.html. Please refer to that document if the explanations listed here are not complete enough for you.
| |
|
| |
| Fig 2.1 Generalized Command Structure
| |
|
| |
| FLAP
| |
| + Command Start (byte: 0x2a)
| |
| + Channel ID (byte)
| |
| + Sequence Number (word)
| |
| + Data Field Length (word)
| |
| Data Field
| |
| - Usually SNAC Data (variable)
| |
|
| |
| 2.1 FLAP
| |
|
| |
| The FLAP is the protocol that sits at the bottom of everything communicated across AIM channels. This generally makes up the first 6 bytes of every AIM command. If this protocol is not obeyed, the OSCAR server will disconnect the offending client immediatly upon reception of a malformed command. This is not helpful for debuging, to say the least.
| |
|
| |
| 2.1.1 FLAP: Headers
| |
|
| |
| Contained in the FLAP headers are: (in order of appearance)
| |
|
| |
| + Command-Start [byte] (always 0x2a)
| |
| + Channel Identification [byte]
| |
| + Sequence Number [word]
| |
| + FLAP Data Field Length [word]
| |
|
| |
| This is followed immediatly by an unterminated FLAP Data Field, which concludes the FLAP command.
| |
|
| |
| 2.1.2 FLAP: Data Field
| |
|
| |
| Normally, the FLAP Data Field contains a SNAC. The FLAP Data Field makes up the rest of the command (there is no FLAP-specific command terminator).
| |
|
| |
| 2.1.3 Sequence Numbers
| |
|
| |
| Why AOL decided to use sequence numbering with TCP is beyond me. The retransmit and data integrity standards of TCP connections make this pointless. So, they're really just there for looks, though that doesn't mean that they can be incorrect. If the server gets an out-of-order command (according to the seqnums, not actual order), you will be disconnected.
| |
|
| |
| The sequence number origins are picked quite randomly. There is no connection between the sequence number set from the server and the set from the client. Sequence numbers are always incremented upward (towards 0xFFFF) for each command sent. If the seqence number does reach 0xFFFF, it will wrap to 0x0000, for obvious reasons. If you start a new connection, it is recommended that a new sequence number origin is picked for that connection, for purposes of internal coherency. Sequence numbers are independent of channels: there's a single series of sequence numbers per TCP connection (per socket). See section 2.1.4 for more information.
| |
|
| |
| 2.1.4 Channels
| |
|
| |
| Channels are the method used to multiplex seperate paths of communication across the same TCP socket. These are analogous to TCP/UDP port numbers. Four channels are currently used by OSCAR:
| |
|
| |
| + 0x01 - New Connection Negotiation
| |
| + 0x02 - SNAC data (non connection-oriented data)
| |
| + 0x03 - FLAP-level Error
| |
| + 0x04 - Close Connection Negotiation
| |
|
| |
| After a new connection (socket) is set up using channel 0x01, data should only be carried on channel 0x02, until a low-level FLAP error occurs (channel 0x03) or there is planned termination, which gets "negotiated" (on channel 0x04). Most live events processed during the lifespan of the client are done over channel 0x02. SNACs are never transmitted on any channel other than 0x02.
| |
|
| |
| 2.1.5 Features of FLAP
| |
|
| |
| [Not yet.]
| |
|
| |
| 2.1.6 Thoughts on FLAP Implementation
| |
|
| |
| The best way to read an incoming FLAP command is to first read only the starting 6 bytes (the FLAP headers). From these 6bytes, you can determine how many more bytes you need to read to complete the command, and how much memory you need to allocate to store it. Never read more or less than the number of bytes specified in the FLAP headers, or your read will result in a truncated or uninterpretable command. (If you read too much, you will probably end up reading the start of the next command, which is bad. Lost data is unacceptable in the AIM standard.)
| |
|
| |
| Because every command must follow FLAP guidelines, I'd recommend using a low-level routine to add the FLAP headers (normally, this will be the "flush transmit queue" routine, so that addition of sequence numbers and the rest of the FLAP headers is done as close timewise as possible to the command being put on the wire). This is the best way to prevent out-of-order seqnums from getting used (which, as stated earlier, is quite fatal).
| |
|
| |
|
| |
| -->
| |
| FLAP (Frame Layer Protocol) provides the packet framing on top of TCP or TLS layer for the OSCAR protocol. Each message sent to and from the AIM backend is encapsulated in a FLAP frame that is easily identified using a 6 byte header followed by a variable length data segment. The payload of a FLAP frame is in most cases a [[Protocols/OSCAR/SNAC|SNAC]]. | | FLAP (Frame Layer Protocol) provides the packet framing on top of TCP or TLS layer for the OSCAR protocol. Each message sent to and from the AIM backend is encapsulated in a FLAP frame that is easily identified using a 6 byte header followed by a variable length data segment. The payload of a FLAP frame is in most cases a [[Protocols/OSCAR/SNAC|SNAC]]. |
|
| |
|
| Line 124: |
Line 61: |
| |} | | |} |
|
| |
|
| === Class: FLAP__MULTICONN_FLAGS ===
| |
|
| |
| These flags control how multiple instances are handled by the servers and if current sessions need to be bumped off when a new session signs on.
| |
|
| |
|
| {| class="wikitable"
| |
| ! Name
| |
| ! Value
| |
| ! Notes
| |
| |-
| |
| | FLAP__MULTICONN_FLAGS_OLD_CLIENT
| |
| | 0x00
| |
| | Don't use
| |
| |-
| |
| | FLAP__MULTICONN_LEVEL_MULTI
| |
| | 0x01
| |
| | This is a recent client that understands multiple instances
| |
| |-
| |
| | FLAP__MULTICONN_LEVEL_SINGLE
| |
| | 0x03
| |
| | This is a recent client that understands multiple instances but does not want them
| |
| |}
| |
|
| |
|
| [[Category:Stub]] | | [[Category:Stub]] |
FLAP (Frame Layer Protocol) provides the packet framing on top of TCP or TLS layer for the OSCAR protocol. Each message sent to and from the AIM backend is encapsulated in a FLAP frame that is easily identified using a 6 byte header followed by a variable length data segment. The payload of a FLAP frame is in most cases a SNAC.
The header contains the frame type, a sequence number, and the length of the following data segment. The sequence number is independently sequential in each direction. Packets from the server to client have one sequence number, while the packets from the client to server have a different independently increasing number.
If the server receives a sequence number out of order it will terminate the connection. A common mistake is to use a uint8 (byte) to represent the sequence number, which will roll over at 255 and cause the server to disconnect the client.
| Name
|
Type
|
Notes
|
| FLAP__MARKER
|
uint8 (byte)
|
ASTERISK (literal ASCII "*")
|
| FLAP__FRAME
|
uint8 (byte)
|
Class: FLAP__FRAME_TYPE
|
| FLAP__SEQUENCE
|
uint16 (word)
|
Initialized to a random value, increments for each send
|
| FLAP__LENGTH
|
uint16 (word)
|
Length of data, does not include the 6 byte header length
|
Class: FLAP__FRAME
There are several different frame types, with the most common being the DATA frame.
| Name
|
Value
|
Notes
|
| FLAP__FRAME_SIGNON
|
0x01
|
Initialize the FLAP connection
|
| FLAP__FRAME_DATA
|
0x02
|
Messages using the FLAP connection, usually a SNAC message
|
| FLAP__FRAME_ERROR
|
0x03
|
A FLAP error - rare
|
| FLAP__FRAME_SIGNOFF
|
0x04
|
Close down the FLAP connection gracefully
|
| FLAP__FRAME_KEEP_ALIVE
|
0x05
|
Send a heartbeat to server to help keep connection open
|