Kannel: Open Source WAP and SMS gateway  $Revision: 5037 $
wap.h
Go to the documentation of this file.
1 /* ====================================================================
2  * The Kannel Software License, Version 1.0
3  *
4  * Copyright (c) 2001-2016 Kannel Group
5  * Copyright (c) 1998-2001 WapIT Ltd.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Kannel Group (http://www.kannel.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Kannel" and "Kannel Group" must not be used to
28  * endorse or promote products derived from this software without
29  * prior written permission. For written permission, please
30  * contact org@kannel.org.
31  *
32  * 5. Products derived from this software may not be called "Kannel",
33  * nor may "Kannel" appear in their name, without prior written
34  * permission of the Kannel Group.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE KANNEL GROUP OR ITS CONTRIBUTORS
40  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
41  * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
42  * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
43  * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
44  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
45  * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
46  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
47  * ====================================================================
48  *
49  * This software consists of voluntary contributions made by many
50  * individuals on behalf of the Kannel Group. For more information on
51  * the Kannel Group, please see <http://www.kannel.org/>.
52  *
53  * Portions of this software are based upon software originally written at
54  * WapIT Ltd., Helsinki, Finland for the Kannel project.
55  */
56 
57 /*
58  * wap.h - public interface to WAP protocol library
59  *
60  * The WAP protocol library consists of separate layers, which each run
61  * in their own thread. The layers are normally used together and will
62  * communicate with each other, but they can be used separately by
63  * specialized applications.
64  *
65  * Communication between layers is done by sending WAPEvent structures.
66  * These events are passed to dispatch functions. Each layer has its
67  * own dispatch function which is responsible for queueing the event
68  * for that layer.
69  *
70  * The application using this library has to provide an application layer
71  * and a datagram layer. These layers do not have to be implemented in
72  * any particular way and do not have to run in their own threads, but
73  * they do have to provide dispatch functions.
74  *
75  * In general, if a layer receives an event that it does not know how
76  * to handle, it will report this and ignore the event.
77  */
78 
79 #ifndef WAP_H
80 #define WAP_H
81 
82 #include "wap_events.h"
83 #include "wap_addr.h"
84 
86 
87 /*
88  * Generic dispatch function that takes T_DUnitdata_Ind events and
89  * figures out to which layer they should be sent, by recognizing
90  * well-known port numbers and by inspecting the datagram contents.
91  * It also unpacks WTP events before dispatching, so that the WTP
92  * thread is not burdened by this.
93  */
95 
96 /*
97  * Generic startup function that initializes all the layers and
98  * chains their dispatch functions together.
99  */
100 void wap_init(wap_dispatch_func_t *datagram_dispatch,
101  wap_dispatch_func_t *application_dispatch);
102 
103 /*
104  * Undoes what wap_init did.
105  */
106 void wap_shutdown(void);
107 
108 
109 /*
110  * Datagram layer
111  *
112  * This layer is not provided by libwap itself. The application is
113  * expected to create one, by:
114  * - providing a dispatch function that takes T_DUnitdata_Req
115  * events (outgoing datagrams)
116  * - passing incoming datagrams to the right layer, either by
117  * calling the layer's dispatch function directly or by calling
118  * wap_dispatch_datagram().
119  */
120 
121 
122 /*
123  * Transaction layer, responder
124  *
125  * This layer implements the Responder side of WTP.
126  * Its dispatch function takes events of these types:
127  *
128  * RcvInvoke, RcvAck, RcvAbort, RcvErrorPDU,
129  * TR_Invoke_Res, TR_Result_Req, TR_Abort_Req,
130  * TimerTO_A, TimerTO_R, TimerTO_W
131  *
132  * FIXME It also takes T_DUnitdata_Ind events, which it will unpack into one
133  * of the Rcv* events and then process.
134  *
135  * This layer will dispatch T_DUnitdata_Req events to the datagram layer,
136  * and these event types to the session layer:
137  *
138  * TR_Invoke_Ind, TR_Result_Cnf, TR_Abort_Ind
139  *
140  * Timer_freq is the timer 'tick' used. All wtp responder timers are
141  * multiplies of this value.
142  */
143 void wtp_resp_init(wap_dispatch_func_t *datagram_dispatch,
144  wap_dispatch_func_t *session_dispatch,
145  wap_dispatch_func_t *push_dispatch,
146  long timer_freq);
148 void wtp_resp_shutdown(void);
149 
150 /*
151  * Transaction layer, initiator
152  *
153  * This layer implements the Initiator side of WTP.
154  * FIXME Currently only class 0 and 1 are implemented.
155  * Its dispatch function takes events of these types:
156  *
157  * RcvAck, RcvAbort, RcvErrorPDU
158  * TR_Invoke_Req, TR_Abort_Req
159  * TimerTO_R
160  *
161  * FIXME It also takes T_DUnitdata_Ind events, which it will unpack into one
162  * of the Rcv* events and then process.
163  *
164  * This layer will dispatch T_DUnitdata_Req events to the datagram layer,
165  * and these event types to the session layer:
166  *
167  * TR_Invoke_Cnf, TR_Abort_Ind
168  *
169  * Timer_freq is a timer 'tick'. All initiator timer values are multiplies
170  * of it.
171  */
172 void wtp_initiator_init(wap_dispatch_func_t *datagram_dispatch,
173  wap_dispatch_func_t *session_dispatch,
174  long timer_freq);
176 void wtp_initiator_shutdown(void);
177 
178 /*
179  * Session layer, connectionless mode
180  *
181  * This layer implements Connectionless WSP.
182  * FIXME Currently only the server side is implemented.
183  * Its dispatch function takes events of these types:
184  *
185  * T_DUnitdata_Ind
186  * S_Unit_MethodResult_Req
187  *
188  * This layer will dispatch T_DUnitdata_Req events to the datagram layer,
189  * and S_Unit_MethodInvoke_Ind events to the application layer.
190  */
191 void wsp_unit_init(wap_dispatch_func_t *datagram_dispatch,
192  wap_dispatch_func_t *application_dispatch);
194 void wsp_unit_shutdown(void);
195 
196 
197 /*
198  * Session layer, connection-oriented mode, server side
199  *
200  * This layer implements the server side of connection-oriented WSP.
201  * FIXME Not all defined service primitives are supported yet.
202  * Its dispatch function takes events of these types:
203  *
204  * TR_Invoke_Ind, TR_Result_Cnf, TR_Abort_Ind
205  * S_Connect_Res, S_Resume_Res
206  * S_MethodInvoke_Res, S_MethodResult_Res
207  * Disconnect_Event, Suspend_Event (internal)
208  *
209  * This layer will dispatch events of these types to the application layer:
210  *
211  * S_Connect_Ind, S_Disconnect_Ind,
212  * S_Suspend_Ind, S_Resume_Ind,
213  * S_MethodInvoke_Ind, S_MethodResult_Cnf, S_MethodAbort_Ind
214  *
215  * and events of these types to the WTP Responder layer:
216  *
217  * TR_Invoke_Res, TR_Result_Req, TR_Abort_Req
218  *
219  * and events of these types to the WTP Initiator layer:
220  *
221  * (none yet)
222  */
223 void wsp_session_init(wap_dispatch_func_t *responder_dispatch,
224  wap_dispatch_func_t *initiator_dispatch,
225  wap_dispatch_func_t *application_dispatch,
226  wap_dispatch_func_t *ota_dispatch);
228 void wsp_session_shutdown(void);
229 
230 
231 /*
232  * Session layer, connection-oriented mode, client side
233  *
234  * FIXME Not implemented yet.
235  */
236 
237 void wsp_push_client_init(wap_dispatch_func_t *dispatch_self,
238  wap_dispatch_func_t *dispatch_wtp_resp);
239 void wsp_push_client_shutdown(void);
241 
242 /*
243  * Application layer
244  *
245  * This layer is not provided by libwap itself. The application is
246  * expected to create one, by providing a dispatch function to the
247  * session layer that takes events of these types:
248  *
249  * S_Connect_Ind, S_Disconnect_Ind,
250  * S_Suspend_Ind, S_Resume_Ind,
251  * S_MethodInvoke_Ind, S_MethodResult_Cnf, S_MethodAbort_Ind
252  * S_Unit_MethodInvoke_Ind (from wsp_unit)
253  *
254  * For most of these events the application layer is expected to send
255  * a response back to the session layer.
256  */
257 
258 #endif
void wtp_initiator_init(wap_dispatch_func_t *datagram_dispatch, wap_dispatch_func_t *session_dispatch, long timer_freq)
Definition: wtp_init.c:168
void wsp_session_shutdown(void)
Definition: wsp_session.c:211
void wtp_resp_shutdown(void)
Definition: wtp_resp.c:235
void wap_shutdown(void)
void wsp_push_client_init(wap_dispatch_func_t *dispatch_self, wap_dispatch_func_t *dispatch_wtp_resp)
void wsp_push_client_dispatch_event(WAPEvent *e)
void wsp_unit_dispatch_event(WAPEvent *event)
Definition: wsp_unit.c:124
void wtp_initiator_shutdown(void)
Definition: wtp_init.c:188
void wap_dispatch_datagram(WAPEvent *event)
Definition: wap.c:68
void wsp_unit_shutdown(void)
Definition: wsp_unit.c:113
WAPEvent * event
Definition: timers.c:138
void wtp_resp_dispatch_event(WAPEvent *event)
Definition: wtp_resp.c:253
void wsp_session_dispatch_event(WAPEvent *event)
Definition: wsp_session.c:228
void wap_init(wap_dispatch_func_t *datagram_dispatch, wap_dispatch_func_t *application_dispatch)
void wsp_push_client_shutdown(void)
void wtp_resp_init(wap_dispatch_func_t *datagram_dispatch, wap_dispatch_func_t *session_dispatch, wap_dispatch_func_t *push_dispatch, long timer_freq)
Definition: wtp_resp.c:211
void wsp_session_init(wap_dispatch_func_t *responder_dispatch, wap_dispatch_func_t *initiator_dispatch, wap_dispatch_func_t *application_dispatch, wap_dispatch_func_t *ota_dispatch)
Definition: wsp_session.c:193
void wtp_initiator_dispatch_event(WAPEvent *event)
Definition: wtp_init.c:204
void wsp_unit_init(wap_dispatch_func_t *datagram_dispatch, wap_dispatch_func_t *application_dispatch)
Definition: wsp_unit.c:100
void wap_dispatch_func_t(WAPEvent *event)
Definition: wap.h:85
static long timer_freq
Definition: wapbox.c:104
See file LICENSE for details about the license agreement for using, modifying, copying or deriving work from this software.