FreeCalypso > hg > freecalypso-docs

annotate SIM-data-formats @ 84:d2fef140ed53

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
CMU200-maintenance-notes: typo fix
author Mychaela Falconia <falcon@freecalypso.org>
date Thu, 13 Jan 2022 19:07:19 +0000
parents ce044aa49baf
children 7609ff4be49f
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
38
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
1 FreeCalypso is developing a family of several different tools that operate on
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
2 SIM cards and user data (primarily phonebooks) stored in them, accessing the
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
3 same underlying data through various mechanisms:
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
4
39
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
5 * fc-simtool in our FC SIM tools suite operates on SIM cards inserted into a
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
6 smart card "reader" device, without going through any kind of phone or other
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
7 GSM device - most direct manipulation of SIM user data content.
38
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
8
39
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
9 * Our FC host tools suite features a new utility called fc-simint - it is a
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
10 front end to fc-simtool that operates on SIM cards inserted into Calypso
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
11 phones or FC modem boards, working on the same principle as fc-loadtool
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
12 (suspending and bypassing the Calypso device's regular operational firmware),
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
13 but operating on the device's SIM interface rather than its flash.
38
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
14
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
15 * We have a FreeCalypso User Phone Tools suite that communicates with FC modem
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
16 boards and the future FC phone handset via AT commands. We have plans to add
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
17 phonebook manipulation commands to this suite (based on AT+CPBR and AT+CPBW),
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
18 reading and writing phonebook data files in the same format as fc-simtool.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
19
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
20 Because we have several different tools (some already written, others only
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
21 planned) that will need to read and write exactly the same data formats, and
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
22 because these tools will have to live in different source repositories (totally
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
23 different underlying hardware and system library requirements), the data format
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
24 specification needs to be global and independent of particular hw tools - it is
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
25 the present document.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
26
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
27 GSM 03.38 / 23.038 string representation
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
28 ========================================
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
29
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
30 The world of GSM does not use ASCII - in all places where ASCII strings would
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
31 appear in the world of ordinary computing, GSM uses its own different 7-bit
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
32 character set instead, defined in GSM TS 03.38 or 3GPP TS 23.038. Many SIM card
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
33 data files (including phonebooks) contain so-called alpha fields in which GSM
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
34 03.38 (not ASCII!) characters are packed into 8-bit bytes, with the high bit
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
35 zeroed. (These alpha fields also allow alternative UCS-2 encodings,
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
36 distinguished by the high bit being set - but we handle this case separately.)
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
37 Some other SIM card data files (EF_PNN for example) contain GSM 03.38 7-bit text
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
38 strings packed into bytes like in SMS.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
39
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
40 However, when we store text strings (such as phonebook contact names) that have
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
41 been read out of a SIM (or are intended to be written to a SIM) in UNIX text
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
42 files, or pass them around in command line arguments, we need an ASCII-based
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
43 representation of these text strings that are encoded in GSM7 in the actual
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
44 GSM/SIM world. Furthermore, our ASCII representation needs to be 100% lossless
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
45 and well-defined.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
46
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
47 Our function for lossless conversion of GSM 03.38 strings to ASCII operates as
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
48 follows:
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
49
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
50 * The output is always enclosed in double-quote characters, as in "text string".
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
51
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
52 * All GSM7 code points that map to characters that are also present in ASCII
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
53 translate to these ASCII characters: for example, GSM7 code 0x00 becomes '@',
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
54 and GSM7 code 0x02 becomes '$'.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
55
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
56 * Any double-quote characters in the data are escaped with a backslash,
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
57 becoming \"
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
58
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
59 * GSM7 escape sequences for ASCII characters [\]^ and {|}~ are recognized and
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
60 converted to these ASCII characters; \ is then escaped in the output as \\
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
61
39
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
62 * GSM7 escape sequence for the Euro currency symbol is recognized and converted
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
63 to \E
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
64
38
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
65 * GSM7 code points corresponding to CR and LF are represented as \r and \n
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
66
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
67 * GSM7 escape characters that are not part of a valid sequence for [\]^ or {|}~
39
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
68 (or for \E) are represented as \e
38
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
69
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
70 * All other GSM7 characters that cannot be represented in ASCII in any other
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
71 way are represented as \xX escapes, where xX is a two-digit hexadecimal number
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
72 in the range between 00 and 7F, inclusive.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
73
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
74 The result of these rules is as follows:
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
75
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
76 * If the text item consists entirely of characters that exist in ASCII (the most
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
77 common use case), it will appear naturally in ASCII, even if it contains
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
78 characters like '@' and '$' that have different code points in GSM7, or
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
79 characters in the [\]^ and {|}~ sets that require escaping in GSM7.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
80
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
81 * Any text item containing weird characters will still be converted losslessly,
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
82 so it can be written back into the SIM or decoded manually by a GSM7-knowing
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
83 user, and the representation in data files and command output is always
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
84 printable ASCII, nothing else.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
85
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
86 * In cases where an occasional weird character appears in an otherwise ASCII-
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
87 dominated string, it is easy to both mentally decode and manually enter such
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
88 characters when necessary. For example, if one of your SIM contacts is a lady
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
89 named Michele who spells her name in the French way, with an accent grave on
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
90 the first 'e' (non-ASCII character U+00E8), her name shall be entered as
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
91 "Mich\04le", nicely preserving the needed non-ASCII character whose GSM 03.38
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
92 code point is 0x04.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
93
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
94 When a string argument that is destined for conversion to GSM7 is parsed, our
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
95 input parser always interprets any backslash (\) characters as escapes; it
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
96 understands all of the same escapes sequences which we emit in output:
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
97
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
98 \" literal "
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
99 \\ literal \ (encoded in GSM 03.38 as another form of escape)
39
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
100 \E Euro currency symbol (ditto)
38
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
101 \e GSM 03.38 escape character 0x1B
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
102 \n GSM 03.38 LF character 0x0A
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
103 \r GSM 03.38 CR character 0x0D
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
104 \xX GSM 03.38 code point xX, passed through literally
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
105
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
106 If the input contains ASCII characters which do not exist in GSM7 (` and all
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
107 control characters except \n and \r), it is an error.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
108
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
109 If our ASCII-to-GSM7 conversion functions are given 8-bit input, such input is
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
110 interpreted as ISO 8859-1: any 8859-1 high characters that have GSM7
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
111 counterparts will be translated accordingly. (Non-GSM7-mappable high characters
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
112 are an error just like non-GSM7-mappable ASCII chars.) However, our output is
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
113 always 7-bit ASCII only, using \xX escapes for GSM 03.38 characters that fall
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
114 outside of ASCII.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
115
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
116 Phonebook file format
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
117 =====================
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
118
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
119 fc-simtool pb-dump command displays SIM phonebook content on the terminal or
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
120 saves it in a file in the format defined here, and other tools such as
39
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
121 fc-simtool pb-restore and pb-update commands need to be able to read back the
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
122 same format losslessly. The phonebook file format is hereby shown by way of
ce044aa49baf SIM-data-formats: minor updates, including \E addition
Mychaela Falconia <falcon@freecalypso.org>
parents: 38
diff changeset
123 example:
38
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
124
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
125 #1: #646#,0x81 "Check Minutes"
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
126 #2: #674#,0x81 "Check Text Usage"
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
127 #3: #225#,0x81 "Check Balance"
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
128 #4: 8675309,0x81 "Jenny"
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
129 #5: 88211016401,0x91 "sysmoUSIM-SJS1 MSISDN"
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
130 #6: 44444,0x81 HEX 810B0893BEC03ABEBC209A9FA1A1
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
131 #7: *123#,0x81 ""
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
132 #8: 5551234,0x81 "HEX magic spells by Mich\04le"
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
133
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
134 The rules are as follows:
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
135
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
136 * Each line in the file format represents one phonebook record.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
137
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
138 * The decimal number between the initial '#' and the following ':' is the
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
139 record number in the phonebook, between 1 and 255 as in the SIM protocol
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
140 READ RECORD and UPDATE RECORD commands.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
141
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
142 * The phone number is always given without quotes, and consists only of digits
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
143 and '*' and '#' characters - no '+' international symbol is allowed in this
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
144 file format.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
145
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
146 * The TON/NPI byte is required, is always given in hex as 0xXX (no other form
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
147 allowed in this file format), and is separated from the phone number digit
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
148 string by a comma. Note how this byte usually equals 0x91 for international
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
149 numbers (those entered with a '+' in typical UIs) or 0x81 otherwise.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
150
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
151 * Either a quoted-string or a hex-string is always present at the end of each
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
152 record, giving the alpha tag for the phonebook entry. This field is
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
153 mandatory in the file format; if there is no alpha tag (really meaning empty
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
154 alpha tag), the line ends with empty quoted-string "".
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
155
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
156 * Quoted-strings for the alpha tag are used for either empty/null or
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
157 GSM7-encoded alpha tags; hex-strings are used for UCS2-encoded alpha tags.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
158
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
159 * The format of hex-string alpha tags is as shown in entry #6 in the example
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
160 above - this example gives a contact name in Russian. (Full decoding of this
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
161 contact name is left as an exercise for adventurous readers - see
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
162 ETSI TS 102 221 Annex A and the Cyrillic block of Unicode.)
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
163
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
164 * Hex-strings can be used for any arbitrary bytes in the alpha tag, but are only
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
165 needed for UCS-2 encodings. Every possible GSM7 string can be represented in
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
166 our quoted-string notation.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
167
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
168 * The quoted-string (GSM 03.38) form of the alpha tag must always be quoted,
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
169 even if quotes seem optional like in the "Jenny" example above (record #4).
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
170 The absence of quotes is what allows the HEX keyword to be distinguished:
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
171 compare and contrast records #6 and #8 in the example.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
172
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
173 The above format applies when the almost-never-used CCP and EXT bytes in the
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
174 phonebook record both equal 0xFF, meaning not used. In the unlikely case when
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
175 these fields are used, the following extra fields are added to the line-based
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
176 representation:
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
177
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
178 * If CCP != 0xFF, a "CCP=%u " field is inserted between the phone number and
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
179 the alpha tag.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
180
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
181 * If EXT != 0xFF, a "EXT=%u " field is inserted between the phone number and
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
182 the alpha tag.
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
183
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
184 * If both CCP and EXT are present, the CCP= field appears before the EXT= field,
ec184dad4877 SIM-data-formats article written
Mychaela Falconia <falcon@freecalypso.org>
parents:
diff changeset
185 same order as in the SIM binary record.