YASS Server Protocol Documentation
The documentation here has been provided to allow developers to understand how data is sent to and from the YASS Server. All data sent sent by the client is in the form of HTTP POST data, and most data returned by the server is encoded with base64, indicated with red text. Variable content is represented in italics.
Confirming a YASS Server URL
This is provided so that the client can verify that a user supplied URL is a valid URL to send and receive data to and from a valid YASS Server.
>>> `req`, `cfm` >>> `msnid`, `msnid` <<< msnid
The msnid listed here is a hash of a user's email address. It can be calculated with code. In PHP:
function get_msnid ($email){
$email = strtolower($email);
for ($msnid=0,$i=0; $i < strlen($email); $i++) {
$msnid *= 101;
$msnid += ord($email[$i]);
while($msnid >= pow(2,32))
$msnid -= pow(2,32);
}
return $msnid;
}
In JavaScript:
function get_msnid(email){
email=email.toLowerCase();
for (var msnid=0,i=0;i < email.length; i++){
msnid *= 101;
msnid += email.charCodeAt(i);
while(msnid >= Math.pow(2,32))
msnid -= Math.pow(2,32);
}
return msnid;
}
Initializing a connection to the server
The initialization commannd logs the client into the server, and provides the information needed to communicate with the server.
>>> `req`, `init` >>> `msnid`, `msnid` >>> `pass`, `old passkey` >>> `tz`, `timezone` <<< 0\n <<< dp;nick;psm;psmmedia;status;statusnumber;bot email;new passkey;uid
The old passkey mentioned here is the passkey used from the previous session. If there is no previous passkey, send an empty string. The third field is the user's timezone, as an integer or floating point number. The data returned by the server starts with a number indicating any errors with the init command. This is 0 on success. See other error values below. The second line returned includes the field names in which to include POST data, the email address of the bot in use, a new passkey, and the userid on the server. The bot email address is used to verify if the bot is on the user's contact list. It is possible that messages from the bot will be blocked unless it is on the contact list, depending on a user's options. The user ID is used in part to form the URL for images created.
Status Updates
The primary goal of YASS is to keep names and statuses up to date. Here's how to do it.
>>> `req`, `update` >>> `msnid`, `msnid` >>> `pass`, `passkey` >>> [`dp`, `msnid.dat`, `multipart/mixed'`, `path`] >>> [`nick`, `display name`] >>> [`psm`, `personal message`] >>> [`psmmedia`, `None|Music|Office|Games`] >>> [`status`, `Online|Busy|...`] >>> [`statusnumber`, `2-9`] <<< 0
After the passkey field, the rest of the fields are optional. The field names here are the same as those received with the init command. The first field listed here is the display picture. It's a bit different from the rest, because it is an image rather than text. The first value indicates the file name as it should be uploaded as, second is the MIME type (this is always the same), third is the full file path to the image on the client computer. Nick and PSM are just that, text forms of the nickname and personal message. PSMMedia should be one of `None`, `Music`, `Office` or `Games`. The selection here determines what icon is shown in front of the personal message on the generated image. Status should be the user's status, such as Online, Away, Busy, etc. A personalised status message can also be sent. StatusNumber is a numeric value representing the actual status value within WLM. See the FAQ for values.
Regenerate a Passkey
Regenerating a passkey is necessary when the client and server keys become mismatched. This is usually only needed when error 4 is returned by the server, but can be allowed to be done manually as well.
>>> `req`, `regen` >>> `msnid`, `msnid` <<< ##
The return value here will be a number, 0 upon success. If not, the number can represent one of two things. Values less than 200 are YASS error codes as below. Greater than 200 are errors returned by the MSN server when trying to send a message. For an explaination of these errors, refer to MSNPiki's explanation of the MSN protocol.
If the command is successful, an instant message will be delivered to the user containing a link to confirm the key regeneration. When this link is clicked, a second message is sent to the user containing the same information as an init command.
<<< ^key=dp;nick;psm;psmmedia;status;statusnumber;botemail;new passkey;uid
Loading Images
This function will load a list of images that a user has saved in slots 0-9. If an image is not saved at a particular slot, an empty string will be returned for that slot. Otherwise, the name of the image as saved by the user will be sent.
>>> `req`, `imgload` >>> `msnid`, `msnid` >>> `pass`, `passkey` <<< img0;img1;img2;img3;img4;img5;img6;img7;img8;img9
Load Image Data
Loading image data will retreive saved settings from the YASS server for an existing image, allowing it to be edited.
>>> `req`, `imgedit` >>> `msnid`, `msnid` >>> `pass`, `passkey` >>> `iid`, `iid` <<< 0\n <<< name;bg_url;bg_colour;bg_x;bg_y;dp;dp_x;dp_y;statusimg;statusimg_x;statusimg_y;statusimg_online;statusimg_busy;statusimg_away;statusimg_offline;statustext;statustext_trailnick;statustext_x;statustext_y;statustext_font;statustext_size;statustext_colour;nick;nick_x;nick_y;nick_xmax;nick_font;nick_size;nick_colour;nick_resize;psm;psm_x;psm_y;psm_xmax;psm_font;psm_size;psm_colour;psm_mediacolour;psm_wrap;psm_music;time;time_x;time_y;time_font;time_size;time_colour;time_date;time_headstring;time_tailstring;psm_office;psm_gamebg_transparent;statustext_shadow;statustext_shadow_colour;nick_shadow;nick_shadow_colour;psm_shadow;psm_shadow_colour;time_shadow;time_shadow_colour
The iid field is the image identifier, which is the same number as the zero-based index of the image names retreived with the imgload command. More detail about the values returned is included in the next section.
Load Image Items
This function is used to load a list of all the backgrounds, icon sets and fonts installed on the server.
>>> `req`, `imgitem` >>> `msnid`, `msnid` >>> `pass`, `passkey` <<< 0\n <<< fontName1;fontName2;...fontNameN\n <<< fontIndex1;fontIndex2;...fontIndexN\n <<< backgroundName1;backgroundName2;...backgroundNameN\n <<< backgroundIndex1;backgroundIndex2;...backgroundIndexN\n <<< onlineName1;onlineName2;...onlineNameN\n <<< onlineIndex1;onlineIndex2;...onlineIndexN\n <<< busyName1;busyName2;...busyNameN\n <<< busyIndex1;busyIndex2;...busyIndexN\n <<< awayName1;awayName2;...awayNameN\n <<< awayIndex1;awayIndex2;...awayIndexN\n <<< offlineName1;offlineName2;...offlineNameN\n <<< offlineIndex1;offlineIndex2;....offlineIndexN\n <<< mediaName1;mediaName2;...mediaNameN\n <<< mediaIndex1;mediaIndex2;...mediaIndexN\n <<< officeName1;officeName2;...officeNameN\n <<< officeIndex1;officeIndex2;...officeIndexN\n <<< gamesName1;gamesName2;...gamesNameN\n <<< gamesIndex1;gamesIndex2;...gamesIndexN
Update or Save an Image
Saving and updating the contents of a saved image is what makes YASS unique. Here's how to send the settings back to the server.
>>> `req`, `imgupdate` >>> `msnid`, `msnid` >>> `pass`, `passkey` >>> `iid`, `iid` >>> `data0`, `name` >>> `data1`, `bg_url` >>> `data2`, `bg_colour` ... >>> `data59`, `time_shadow_colour` <<< 0
0 name (string[20])
A name for the image. Used only for identifiction by the user.
1 bg_url (unsigned integer)
Index value for a background image. Image names and indexes are retreived with the imgitem command.
2 bg_colour (string[7], ^#[A-F0-9]{6}$)
Background colour. Must be in the form of a hexadecimal colour code, eg #123456.
3 bg_x (unsigned integer, 0 > bg_x >= 999)
Width of the total image size. Background image is streched to fit this width.
4 bg_y (unsigned integer, 0 > bg_y >= 999)
Height of the total image size. Background image is streched to fit this height.
5 dp (unsigned integer, 0 => dp >= 4)
Indicates display picture size. 0 indicates not to show a display picture, 1 size of 24x24px, 2 - 48x48px, 3 - 72x72px, 4 - 96x96px
6 dp_x (integer, -96 => dp_x >= 999)
Horizontal position of the display picture. Value indicates left edge of image.
7 dp_y (integer, -96 => dp_y >= 999)
Vertical position of the display picture. Value indicates bottom edge of image.
8 statusimg (unsigned integer, 0 >= statusimg >= 1)
Show a status image. 1 = true.
9 statusimg_x (integer, -200 => statusimg_x >= 999)
Horizontal position for the status image. Value indicates left edge of image.
10 statusimg_y (integer, -200 => statusimg_y >= 999)
Vertical position of the status image. Value indicates bottom edge of image.
11 statusimg_online (unsigned integer)
Index value for an online icon. Image names and indexes are retreived with the imgitem command.
12 statusimg_busy (unsigned integer)
Index value for a busy icon. Image names and indexes are retreived with the imgitem command.
13 statusimg_away (unsigned integer)
Index value for an away icon. Image names and indexes are retreived with the imgitem command.
14 statusimg_offline(unsigned integer)
Index value for an offline icon. Image names and indexes are retreived with the imgitem command.
15 statustext (unsigned integer, 0 >= statustext >= 1)
Show the text version of a user's status. 1 = true.
16 statustext_trailnick (unsigned integer, 0 >= statustext_trailnick >= 1)
Add the status text on the end of the display name. X and Y positions are ignored. 1 = true.
17 statustext_x (unsigned integer, 0 >= statustext_x >= 999)
Horizontal position of status text. The value represents the leftmost edge of the text.
18 statustext_y (unsigned integer, 0 >= statustext_y >= 999)
Vertical position of status text. Measured at the baseline of the text, eg the bottom of the letter x.
19 statustext_font (unsigned integer)
Index value of a named font. Font names and indexes are retreived with the imgitem command.
20 statustext_size (unsigned integer, 6 >= statustext_size >= 48)
Font size of the status text. Must be between 6pt and 48pt.
21 statustext_colour (string[7], ^#[A-F0-9]{6}$)
Font colour of the status text. Must be in the form of a hexadecimal colour code.
22 nick (unsigned integer, 0 >= nick >= 1)
Enable showing of the display name or nickname. 1 = true
23 nick_x (unsigned integer, 0 >= nick_x >= 999)
Horizontal position of the display name text. The value represents the leftmost edge of the text.
24 nick_y (unsigned integer, 0 >= nick_y >= 999)
Vertical position of the display name text. Measured at the baseline of the text.
25 nick_xmax (unsigned integer, 20 >= nick_xmax >= 999)
Maximum width of the display name in pixels. If the text is larger than this value, it will either be truncated, or the font size adjusted depending on the value of nick_resize. If statustext_trailnick is enabled, its size will be included with this value.
26 nick_font (unsigned integer)
Index value of a named font for the display name. Font names and indexes are retreived with the imgitem command.
27 nick_size (unsigned integer, 6 >= nick_size >= 48)
Font size of the display name. Must be between 6pt and 48pt.
28 nick_colour (string[7], ^#[A-F0-9]{6}$)
Font colour of the display name. Must be in the form of a hexadecimal colour code.
29 nick_resize (unsigned integer, 0 >= nick_resize >= 1)
If nick_resize is enabled, the font size will decrease in increments of 2 until the display name size is less than nick_xmax. Otherwise, the display name will be truncated to fit.
30 psm (unsigned integer, 0 >= psm >= 1)
Enable showing of the personal message and current media. 1 = true
31 psm_x (unsigned integer, 0 >= psm_x >= 999)
Horizontal position of the personal message text. The value represents the leftmost edge of the text.
32 psm_y (unsigned integer, 0 >= psm_y >= 999)
Vertical position of the display name text. Measured at the baseline of the text.
33 psm_xmax (unsigned integer, 20 >= psm_xmax >= 999)
Maximum width of the personal message in pixels. If the text is larger than this value, the text will either wrap to a second line or be truncated, depending on the value of psm_wrap.
34 psm_font (unsigned integer)
Index value of a named font for the personal message. Font names and indexes are retreived with the imgitem command.
35 psm_size (unsigned integer, 6 >= psm_size >= 48)
Font size of the personal message. Must be between 6pt and 48pt.
36 psm_colour (string[7], ^#[A-F0-9]{6}$)
Font colour of the personal message. Must be in the form of a hexadecimal colour code.
37 psm_mediacolour (string[7], ^#[A-F0-9]{6}$)
Font colour of the personal message when media information is displayed. Must be in the form of a hexadecimal colour code.
38 psm_wrap (unsigned integer, 0 >= psm_wrap >= 1)
When enabled, the personal message will be displayed as 2 lines if it is longer than psm_xmax. The vertical position of the first line is raised 50% of the height of the text. If disabled, the personal message is truncated if bigger than psm_xmax.
39 psm_music (unsigned integer)
Index of the image to be displayed when the 'Music' media type is shown. Image names and indexes are retreived with the imgitem command.
40 time (unsigned integer, 0 >= time >= 1)
Enable displaying of a timestamp.
41 time_x (unsigned integer, 0 >= time_x >= 999)
Horizontal position of the timestamp text. The value represents the leftmost edge of the text.
42 time_y (unsigned integer, 0 >= time_y >= 999)
Vertical position of the timestamp text. Measured at the baseline of the text.
43 time_font (unsigned integer)
Index value of a named font for the timestamp. Font names and indexes are retreived with the imgitem command.
44 time_size (unsigned integer, 6 >= time_size >= 48)
Font size of the timestamp. Must be between 6pt and 48pt.
45 time_colour (string[7], ^#[A-F0-9]{6}$)
Font colour of the timestamp. Must be in the form of a hexadecimal colour code.
46 time_headstring (string[20])
Text to be displayed at the beginning of the timespamp.
47 time_date (string[20])
Format of the timestamp. This follows the syntax of the PHP date function.
48 time_tailstring (string[20])
Text to be displayed at the end of the timespamp.
49 psm_office (unsigned integer)
Index of the image to be displayed when the 'Office' media type is shown. Image names and indexes are retreived with the imgitem command.
50 psm_game (unsigned integer)
Index of the image to be displayed when the 'Games' media type is shown. Image names and indexes are retreived with the imgitem command.
51 bg_transparent (unsigned integer, 0 >= bg_transparent >= 1)
If enabled, the background will be drawn with a transparent background instead of a solid colour.
52 statustext_shadow (unsigned integer, 0 >= statustext_shadow >= 1)
If enabled, the status text will be drawn a second time, x+1 and y+1 of the original location to create a shadow appearance.
53 statustextshadow_colour (string[7], ^#[A-F0-9]{6}$)
Font colour of the status text shadow. Must be in the form of a hexadecimal colour code.
54 nick_shadow (unsigned integer, 0 >= nick_shadow >= 1)
If enabled, the display name will be drawn a second time, x+1 and y+1 of the original location to create a shadow appearance.
55 nick_shadow_colour (string[7], ^#[A-F0-9]{6}$)
Font colour of the display name shadow. Must be in the form of a hexadecimal colour code.
56 psm_shadow (unsigned integer, 0 >= psm_shadow >= 1)
If enabled, the personal message will be drawn a second time, x+1 and y+1 of the original location to create a shadow appearance.
57 psm_shadow_colour (string[7], ^#[A-F0-9]{6}$)
Font colour of the personal message shadow. Must be in the form of a hexadecimal colour code.
58 time_shadow (unsigned integer, 0 >= time_shadow >= 1)
If enabled, the timestamp will be drawn a second time, x+1 and y+1 of the original location to create a shadow appearance.
59 time_shadow_colour (string[7], ^#[A-F0-9]{6}$)
Font colour of the timestamp shadow. Must be in the form of a hexadecimal colour code.
Delete a Saved image
This function deletes a saved image. Once deleted, the image cannot be recovered or restored.
>>> `req`, `imgitems` >>> `msnid`, `msnid` >>> `pass`, `passkey` >>> `iid`, `iid` <<< 0
Load Saved Templates
In addition to being able to create an image from scratch, YASS also has the ability to create an image from a template image. A list of available templates can be retreived with this.
>>> `req`, `tplload` >>> `msnid`, `msnid` >>> `pass`, `passkey` <<< 0\n <<< templateId1;templateId2;...templateIdN\n <<< templateName1;templateName2;...templateNameN\n <<< templateCreator1;templateCreator2;...templateCreatorN
Save a Template
Once the list of available templates is loaded, one can then be saved to an image slot on the users' list. The image ID that is provided must not currently have an image saved to that spot.
>>> `req`, `tplsave` >>> `msnid`, `msnid` >>> `pass`, `passkey` >>> `iid`, `iid` >>> `tid`, `tid` <<< 0
Error List
On occasion, things do go wrong. YASS is no exception. Here is a list of error / exit codes that are used throughout the protocol.
0 No error, command executed successfully
1 User does not exist in database
2 (Not used)
4 Passkey is incorrect. Regenerate a new key to resolve.
8 Error uploading display picture. This can happen for a number of reasons, including:
- /resources/dp folder does not exist on the server, or does not have write permissions
- Image filesize is more than 100kb
- wrong MIME type sent
16 Insufficient parameters (A field is missing from the POST data)
32 Failed to save image data, did not pass validation. A text description will also be included with this error
64 Internal database error, error running a SQL statement
128 Internal database error, cannot connect to the MySQL database