8 Now that we know in some detail the workings of the protocols it makes
9 sense to organise the gnokii code to fit them better. This should mean
10 that when new models come out, it is easier to get the code in place to
11 support them. It is hoped that the new structure will also work for other
17 Application (gnokii/xgnoki)
23 Phone specific code (eg nk7110.c)
24 | SM_SendMessage(), SM_Wait(), SM_Loop()
26 | SendMessage(), Loop()
27 Link specific code (eg fbus.c)
39 The gnokii application (eg gnokii, xgnokii) decides on the phone type and
40 required connection method from the config file. It then calls the
41 gsm-api init code which in turn calls the init code for the correct phone.
42 This code is located in a series of files phone/*.c. This code creates a
43 GSM_State structure (which contains a GSM_Link structure) and passes this
44 to the common code for the specific link (eg FBUS_Initialise, contained in
45 fbus.c). The link code fills in the GSM_Link part of state (and
46 also stores state to use later). The phone code chooses the appropriate
47 link and is free to perform any phone specific init. It then initialises
48 the StateMachine by passing it the state struct and a GSM_Phone struct.
53 The link serves to deal with bits of the phone protocol which are common to
54 every exchange for that particular phone.
56 The GSM_Link structure is used to contain any information about the link
57 which is required by the StateMachine. Two vital functions in the link
58 are SendMessage and Loop:
60 SendMessage(u16 messagesize, u8 messagetype, void *message)
61 is the function called by the statemachine code to send a message 'down
62 the pipe'. The parameters are intended to be generic (though with
63 obvious origins :-) For example 'at' commands could be enumerated and
64 passed as messagetype.
66 Loop(struct timeval *timeout)
67 is a function which must be called regularly by the statemachine code
68 to enable to link code to process date from the phone. This is due to
69 the code now being single threaded and using select/poll. The timeout
70 passed can therefore be used to make this function block for a while
73 In the loop function, the link code checks for any incoming messages from
74 the phone. Any received correctly are passed up to the statemachine code.
79 All common/*.c files contain the code that is general and is used by all
80 of the phones. The functions within should convert the gnokii internal
81 structures into the frames (without the header) that can be sent to the
82 phone and understood by it. It's obvious that this layer should be phone
83 independent. All the phone specific stuff should be done in the phone layer.
84 In the case when phone frames are similiar but not the same, the phone layer
85 can export some help structures to let be the code shared in the middle
86 layer. Using the middle layer is optional. Currently almost no code does use
87 it. Although it is recommended to use it to avoid the code duplication and
88 to keep clean the phone drivers.
93 The phone/*.c code therefore basically contains code to package up and
94 unpack information from the phone specific format to generic gnokii
95 structures (eg GSM_Bitmap). However, it is also at the top of the tree
96 and contains functions called by the application. Generally there are
97 three types of exchanges that can occur. Firstly the computer can send
98 the phone a command and expect no answer (not including acks etc which
99 are dealt with by the phone code). Secondly the computer may send a command
100 and expect a response within a certain time - often containing useful
101 information. Lastly the phone may send the computer unrequested
102 information (ring!). Therefore the functions in the phone code need to
103 process one of these three things:
105 1) Just sending out is easy - we simply call SM_SendMessage - which in
106 turn calls the link sendmessage.
108 2) Command and response. There are two ways to do this. In both cases we
109 start out by sending a message via the statemachine. Next we either a)
110 wait for the reply or b) wait for some other code to process the reply.
111 My (*new improved*!!!) suggestion is that the statemachine calls phone
112 functions (like parts of DispatchMessage) which process the received data
113 into a generic structure tagged with the data type (one function for each
114 data type). This is returned to the statemachine. The statemachine then
115 returns this 'baggage' to the other part of the phone code which is
118 3) Notification. Here, as for 2) the statemachine calls some phone code,
119 but the phone code merely remembers it and does not return any data.
122 So, the phone file contains two types of functions. Some are called by
123 the application (via GSM_Functions) - and some by the statemachine
124 (IncomingFunctions[]). The application ones assemble a request and pass
125 it on down to the statemachine. They then block to the statemachine until
126 the answer is ready. The statemachine recieves data from the link and
127 passes it up to the appropriate IncomingFunction in phone, which returns
128 the answer which is finally passed back to the blocked phone function.
133 This therefore has the following states:
141 When SM_SendMessage is called by the phone (application code), we go to
142 state MessageSent. The message is passed on to the link, but stored
143 internally as well in-case it needs to be resent.
145 If at any point an message from the link is received this is passed onto
146 the phone (incoming) code.
148 If the phone code calls SM_WaitFor, we go to state Waiting. Now if an
149 answer comes back from the phone code (eg a received logo) we store it
150 internally in the statemachine and go to state AnswerReady.
152 When the phone code calls SM_GetAnswer, we pass up the stored answer and
153 go back to Initialised.
155 Note that all of this can, or can not be done as a seperate thread. For
156 now, we will have a SM_Loop function (which blocks for a required time and
157 returns the current state) so that we can work within one thread.
162 This now contains one handy helper function which serves only to call
163 SM_WaitFor, then SM_Loop repeatedly until the state goes to AnswerReady,
164 and then SM_GetAnswer. This is just to save repeating code.
167 -----------------------
169 Note that this leaves the phone code very similar to the basic layout of
170 eg fbus-6110.c but removes all the:
172 static GSM_DateTime *CurrentAlarm;
173 static GSM_Error CurrentAlarmError;
175 ,makes everything well orderd and splits up DispatchMessage into byte
178 -----------------------
185 Within a phone/*.c or link file the functions should be made static. It
186 is therefore not necessary to use prefixes such as FB61_ but this may help
187 code legibility to distiguish the major functions.