format Element

Article
05/23/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Used to specify the format of a text message in an IM session.

Syntax

<Format>string value</Format>

The following sections describe attributes, parent elements, and child elements.

Attributes

None.

Element Information

Parent Element

Element	Description
sendMessage	Sends an IM message to an IM session.

Child Element

Element	Occurrences	Description
None.	not applicable	not applicable

Remarks

The message format specifies the font (FN), effect (EF), color (CO), character set (CS) and pitch and family (PF) used for rendering the text message. The parentheses list the names of the message format attributes.

The value of the Format element is a string of the following form:

FormatName : {AttributeName=AttributeValue; * }

where FormatName is "X-MMS-IM-Format", AttributeName is one of FN, EF, CO, CS, or PF, and AttributeValue depends on AttributeName, the details of which is discussed below:

Font Name (FN)

The FN parameter specifies a font name. The font name must be URL-encoded. For example, to have a font of "MS Sans Serif", you would have to specify FN=MS%20Sans%20Serif. Font names are not case-sensitive and only spaces should be URL-encoded. URL-encoding other characters such as numbers and letters cause unpredictable results. If the receiving client does not have the specified font, it should make judgment based on the PF and CS parameters. Basically, the client should select whichever available font supports the character set specified in CS and is closest to the category specified in PF. If those parameters are not present, the client should just use a default font.

Effects (EF)

The EF parameter specifies optional style effects. Possible effects are bold, italic, underline, and strikethrough. Each effect is referred to by its first letter. For example, to make bold-italic text, include the parameter EF=IB or EF=BI. The order does not matter. Any unknown effects are to be ignored. If there are no effects, just leave the parameter value blank.

Color (CO)

The CO parameter specifies a font color. The value of the CO field is a six-character hexadecimal BGR (blue-green-red, the reverse of the standard RGB order seen in HTML) string. The first two characters represent a hexadecimal number from 00 to ff (hexadecimal for 255) for the intensity of blue, the second two are for green, and the third two are for red. For example, to make a full red color, send CO=0000ff.

Character Set (CS)

Character sets are identified in the CS parameter with one or two hexadecimal digits (leading zeros are dropped by the official client and are ignored if present), representing the numerical value Windows uses for the character set. The following table shows the full list of the predefined character sets that are included with the Microsoft® Windows® operating system.

Character Set	Description
0 - ANSI_CHARSET	ANSI characters
1 - DEFAULT_CHARSET	Font is chosen based solely on name and size. If the described font is not available on the system, Windows substitutes another font.
2 - SYMBOL_CHARSET	Standard symbol set
4d - MAC_CHARSETLT	Macintosh characters
80 - SHIFTJIS_CHARSET	Japanese shift-JIS characters
81 - HANGEUL_CHARSET	Korean characters (Wansung)
82 - JOHAB_CHARSET	Korean characters (Johab)
86 - GB2312_CHARSET	Simplified Chinese characters (China)
88 - CHINESEBIG5_CHARSET	Traditional Chinese characters (Taiwan)
a1 - GREEK_CHARSET	Greek characters
a2 - TURKISH_CHARSET	Turkish characters
a3 - VIETNAMESE_CHARSET	Vietnamese characters
b1 - HEBREW_CHARSET	Hebrew characters
b2 - ARABIC_CHARSET	Arabic characters
ba - BALTIC_CHARSET	Baltic characters
cc - RUSSIAN_CHARSET_DEFAULT	Cyrillic characters
de - THAI_CHARSET	Thai characters
ee - EASTEUROPE_CHARSET	Sometimes called the "Central European" character set, this includes diacritical marks for Eastern European countries
ff - OEM_DEFAULT	Depends on the codepage of the operating system

You should not assume that clients receiving your messages understand all character sets. This character set is arbitrary, but it is advisable to make it the one that causes the most characters to be displayed correctly.

Pitch and Family (PF)

The PF family defines the category that the font specified in the FN parameter falls into. This parameter is used by the receiving client if it does not have the specified font installed. The value is a two-digit hexadecimal number. When programming with Windows APIs, this value is the PitchAndFamily value in RichEdit and LOGFONT.

The first digit of the value represents the font family. Below is a list of numbers for the first digit and the font families they represent.

First Digit	Description
0_ - FF_DONTCARE	Specifies a generic family name. This name is used when information about a font does not exist or does not matter. The default font is used.
1_ - FF_ROMAN	Specifies a proportional (variable-width) font with serifs. An example is Times New Roman.
2_ - FF_SWISS	Specifies a proportional (variable-width) font without serifs. An example is Arial.
3_ - FF_MODERN	Specifies a Monospace font with or without serifs. Monospace fonts are usually modern; examples include Pica, Elite, and Courier New.
4_ - FF_SCRIPT	Specifies a font that is designed to look like handwriting; examples include Script and Cursive.
5_ - FF_DECORATIVE	Specifies a novelty font. An example is Old English.

The second digit represents the pitch of the font — in other words, whether it is monospace or variable-width.

Second Digit	Description
_0 - DEFAULT_PITCH	Specifies a generic font pitch. This name is used when information about a font does not exist or does not matter. The default font pitch is used.
_1 - FIXED_PITCH	Specifies a fixed-width (Monospace) font. Examples are Courier New and Bitstream Vera Sans Mono.
_2 - VARIABLE_PITCH	Specifies a variable-width (proportional) font. Examples are Times New Roman and Arial.

Below are some PF values and example fonts that fit the category.

Examples of PF Value	Description
12	Times New Roman, MS Serif, Bitstream Vera Serif
22	Arial, Verdana, MS Sans Serif, Bitstream Vera Sans
31	Courier New, Courier
42	Comic Sans MS

Examples

<Message>
   <Format>X-MMS-IM-Format: FN=Arial; EF=; CO=000000; CS=1; PF=00</Format>
   <Text>hello world</Text>
</Message>

Share via