Protocols/MSNP/MSNFTP/Invitation

Each invitation message is sent through a switchboard session as a MSG with MIME-Version: 1.0 and a content-type of text/x-msmsgsinvite; charset=UTF-8. The body of an invitation message is a set of fields. As usual, fields may be sent in any order, and any unrecognised fields must be ignored. The complete set of fields is given below. Fields marked "required" must be sent. Fields marked "optional" may be sent, but the receiver should be prepared to cope with messages that don't include them. In file transfer, the client may ignore all optional fields - versions of the official client below 5.0 always ignore optional fields, versions 5.0 and above never do. The exception to this is that if you send a "Connectivity" field, you must handle the "Sender-Connect" field if it is sent in the reply.

The official client will only negotiate in switchboard sessions with exactly two people in them, so if inviter and invitee don't share such a session, the client sending the invitation must first create one. It is not necessary to reply to an invitation in the same session which it was sent. For example, if Alice and Bob are in a switchboard, Alice sends an invitation to Bob, then Carol enters the switchboard, Bob must send his reply in a different switchboard session.

Each message contains one "invitation command". The sequence in which commands must be sent is:

• 1. The inviter sends an INVITE command
• 2. the invitee ACCEPTs the invitation
• 3. If the invitee did not offer to serve, the inviter ACCEPTs
• 4. Either client may then send a CANCEL command with a cancel code of FTTIMEOUT, if there is a problem during transfer. For example, the official client will listen for an incoming connection for 30 seconds, then cancel the offer.

Either party can send a CANCEL command at any time after the first message is sent. No further messages should be sent after this.

Common Fields

All messages in a negotiation include the following fields:

=== Invitation-Command === (required) The type of message being sent. See the protocol section, above for valid invitation commands. ==== Invitation-Cookie ==== (required) A random integer between 1 and 2^32 - 1, uniquely identifying a negotiation (note that a cookie of 0 is invalid). This value is decided by the sender of the INVITE, and must remain constant throughout a negotiation

INVITE Fields

INVITE commands include the following fields:

=== Application-Name === (required) A natural-language description of the class. This can vary - for example, the official client calls the file transfer class File Transfer in English, Filoverføring in Norwegian, and ファイル送信 in Japanese. This should only be used to describe a class to the user - for example, if the Application-GUID isn't recognised

=== Application-GUID === (required) The unique identifier of the class. A class always has the same GUID, and no two classes ever have the same GUID. Strictly speaking, that makes it a CLSID (a GUID used to identify a class). The GUID for file transfer is "{5D3E02AB-6190-11d3-BBBB-00C04F795683}", and for some reason, the official client checks this case-sensitively.

=== Application-File === (required) The name of the file to be sent

=== Application-FileSize === (required) The size in bytes of the file to be sent. If this size differs from the size given during the file transfer session, that value takes priority

=== Connectivity === (optional) If the client knows it cannot receive incoming connections, it should send this with a value of 'N'. The official client decides this based on the initial profile, but you could just as well ask the user if you prefer.

Cancel Fields

Only one field is required by CANCEL commands - Cancel-Code. This is a short reason for cancellation. You should treat this as a free-form string, but the general-purpose codes which have been encountered in the official client are:

FAIL

The receiving client does not know any of the specified Session-protocols

FTTIMEOUT

There was an error transferring the file itself

OUTBANDCANCEL

The switchboard window in which the INVITE message was sent is closing

REJECT

The principal has declined the invitation

REJECT_NOT_INSTALLED

The client does not support that application GUID

TIMEOUT

The client sending an INVITE has got bored of waiting for your ACCEPT (or the principal has cancelled the request)

ACCEPT Fields

The following field exists in all ACCEPT commands:

=== Launch-Application === (required) Instructs the other client (not) to launch an external application. Since file transfer is handled internally by the official client, this is normally "FALSE". I don't know under what condition you would set this to "TRUE"

The ACCEPT command with the offer to serve includes these fields:

=== IP-Address === (required) The primary IP address for the client to connect to. The official client gets the address of your network's Internet gateway from the initial profile.

=== IP-Address-Internal === (optional) The secondary IP address for the client to connect to (if the primary address failed). Recent versions of the official client put the address of your network card here.

=== Port === (required) The primary TCP port your server is listening on. This should be 6891. Some versions of the official client will misbehave if you use a different address. This field is the counterpart to "IP-Address".

=== PortX === (optional) The secondary TCP port your server is listening on. This should be 11178. Some versions of the official client will misbehave if you use a different address. This field is the counterpart to "IP-Address-Internal", so include this field if and only if you include that one.

=== PortX-Internal === (optional) If included, this field must be equal to "PortX". This is probably a work-around for older versions of the official client

=== AuthCookie === (required) A random integer between 1 and 2^32 - 1, used in the file transfer session to uniquely identify the file being sent (in case two files are being sent at once) === Sender-Connect === (optional) Normally, the computer receiving the file initiates a connection to the sender. If the sender should connect to the receiver (e.g. if the sender is behind a firewall), this is sent with a value of "TRUE"

Examples

Here is an example of a successful file transfer invitation between two clients which support the upgraded invitation method.

>>> MSG 12 N 294\r\n
    MIME-Version: 1.0\r\n
    Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n
    \r\n
    Application-Name: File Transfer\r\n
    Application-GUID: {5D3E02AB-6190-11d3-BBBB-00C04F795683}\r\n
    Invitation-Command: INVITE\r\n
    Invitation-Cookie: 85366\r\n
    Application-File: Autoexec.bat\r\n
    Application-FileSize: 187\r\n
    Connectivity: N
<<< MSG bob@hotmail.com Bob 306\r\n
    MIME-Version: 1.0\r\n
    Content-Type: text/x-msmsgsinvite; charset=UTF-8\r\n
    \r\n
    IP-Address: 81.99.77.64\r\n
    IP-Address-Internal: 10.5.1.3\r\n
    Port: 6891\r\n
    PortX: 11178\r\n
    AuthCookie: 544120\r\n
    Sender-Connect: TRUE\r\n
    Invitation-Command: ACCEPT\r\n
    Invitation-Cookie: 227948\r\n
    Launch-Application: FALSE\r\n
    Request-Data: IP-Address: