1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<!-- $Id: phonespec.html 2690 2005-12-19 03:58:14Z skyjunky $ -->
<title>Strings in BitPim</title>
</head>
<body>
<h1>class STRING</h1>
<p>This document describes the operation of the STRING class in
BitPim.
<p>BitPim uses two string types.
The built in python strings for most of the code including the GUI and database,
and a STRING class that is used in the construction of PACKETs for communication
with the phone.
<p> The STRING class is defined in prototypes.py
<p> It translates text in communications with the phone.
It is very specialised for this task and has some features not found in a
regular string objects.
<p>The STRING class converts the python strings into a format that
the phones can understand.
<p>There are several properties (keywords) of a string this class has to make
conversion, how they are set depends on how the phone works.
<pre>
constant
terminator
pad
sizeinbytes
default
raiseonunterminatedread
raiseontruncate
value
pascal
encoding
read_encoding
write_encoding
</pre>
<p><B>constant</B>
<p>(Optional) A constant value. This string can only have one value, L{ValueException}
will be raised if it is set to anything else.
<p><B>terminator</B>
<p>(Default=0 (like c strings)) Set this to the string terminator or 'None' is there is no terminator.
If set there will always be a terminator when writing. The terminator is not returned when getting
the value. The terminator is counted in the length of the string and is sent to the phone.
<p><B>pad</B>
<p>(Default=0) The padding byte used when writing fixed length strings, stripped off
when reading from the phone.
<p><B>sizeinbytes</B>
<p>(Optional) Set if the phone uses fixed length strings.
If not set, then the terminator will be used to find the end of strings on reading.
If not set and the terminator is None, then reads will be entire rest of buffer.
<p><B>default</B>
<p>(Optional) The default value to assign to the string, can be overwritten.
<p><B>raiseonunterminatedread</B>
<p>(Default True) L{NotTerminatedException} will be raised if there is
no terminator on the value being read in. <B>terminator</B> keyword must also be set or this
keyword is ignored.
<p><B>raiseontruncate</B>
<p>(Default True) L{ValueLengthException} will be raised if the supplied value is too large
to fit within <B>sizeinbytes</B>.
<p><B>value</B> <p>
(Optional) Value. Value to assign to the string.
<p><B>pascal</B>
<p>(Default False) Pascal sytle string, the string is preceded with one byte giving the length
of the string (including terminator if there is one)
<p><B>encoding</B>
<p>(Default 'ascii') The charset to use when reading from/writing to a buffer.
<p><B>read_encoding</B>
<p>(Default None) The charset to use to convert the string to unicode when reading from a buffer.
If None then <B>encoding</B> is used to as the charset.
<p><B>write_encoding</B>
<p>(Default None) The charset the string is converted to when writing to a buffer.
If None then <B>encoding</B> is used to as the charset.
<p><B>UNICODE</B>
<p>Internally BitPim uses UNICODE for all text string, most phones
do not.
<p>The STRING class acts as a conversion object to go from
unicode to whatever the phone supports. It does this without the
phone developer having to do anything. It generates it's own exceptions
when it cannot convert the python unicde string to the phone's string format
L{PhoneStringEncodeException} and when it cannot convert the phone's
format to a python unicode string L{PhoneStringDecodeException}. L{PhoneStringEncodeException}
causes the user to see an error message (it is handled gracefully).
L{PhoneStringDecodeException} is not, if you get this then the <B>encoding</B> of the
string is incorrect and needs to be fixed.
<p>The B>sizeinbytes</B> keyword does not mean string length. Some string encoding types
use more than one byte for a character, and some use different numbers of bytes for different
characters (e.g. UTF-8).
<p>STRINGs can be assigned values using '=' like other data types.
<p><B>Example STRING uses in phone PACKETs</B>
<pre>
60 STRING {'raiseonunterminatedread': False, 'raiseontruncate': False } filename "includes full pathname"
23 STRING {'encoding': PHONE_ENCODING, 'raiseonunterminatedread': False, 'raiseontruncate': False } name
* STRING {'terminator': 0xA, 'default':'ams:'} +location_maybe
</pre>
<p>The keyword values are specified inbetween the curly braces.
<p>The number at the start is used as the <B>sizeinbytes</B> keyword. Using a '*' causes it to be left as default.
<p>The advantage of using the <B>sizeinbytes</B> keyword is that you can use non-hardcoded values.
<p>The + before the name of the string means that the value will be set to the default value without having to
be explicitly assigned, used when packets are written to the phone.
<hr>
<!-- Created: Sat Apr 3 08:39:24 Pacific Standard Time 2006 -->
<!-- hhmts start -->
Last modified: Sat Apr 3 08:39:24 Pacific Standard Time 2006
<!-- hhmts end -->
</body>
</html>
|
