Kannel: Open Source WAP and SMS gateway  $Revision: 5037 $
smscconn.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 #ifndef SMSCCONN_H
58 #define SMSCCONN_H
59 
60 /*
61  * SMSC Connection
62  *
63  * Interface for main bearerbox to SMS center connection modules
64  *
65  * At first stage a simple wrapper for old ugly smsc module
66  *
67  * Kalle Marjola 2000
68  */
69 
70 #include "gwlib/gwlib.h"
71 #include "gw/msg.h"
72 
73 /*
74  * Structure hierarchy:
75  *
76  * Bearerbox keeps list of pointers to SMSCConn structures, which
77  * include all data needed by connection, including routing data.
78  * If any extra data not linked to that SMSC Connection is needed,
79  * that is held in bearerbox
80  *
81  * SMSCConn is internal structure for smscconn module. It has a list
82  * of common variables like number of sent/received messages and
83  * and pointers to appropriate lists, and then it has a void pointer
84  * to appropriate smsc structure defined and used by corresponding smsc
85  * connection type module (like CIMD2, SMPP etc al)
86  *
87  * Concurrency notes:
88  *
89  * bearerbox is responsible for not calling cleanup at the same time
90  * as it calls other functions, but must call it after it has noticed that
91  * status == KILLED
92  */
93 
94 typedef struct smscconn SMSCConn;
95 
96 typedef enum {
102  SMSCCONN_DEAD /* ready to be cleaned */
104 
105 typedef enum {
111 
112 typedef struct smsc_state {
113  smscconn_status_t status; /* see enumeration, below */
114  smscconn_killed_t killed; /* if we are killed, why */
115  int is_stopped; /* is connection currently in stopped state? */
116  unsigned long received; /* total number */
117  unsigned long received_dlr; /* total number */
118  unsigned long sent; /* total number */
119  unsigned long sent_dlr; /* total number */
120  unsigned long failed; /* total number */
121  long queued; /* set our internal outgoing queue length */
122  long online; /* in seconds */
123  int load; /* subjective value 'how loaded we are' for
124  * routing purposes, similar to sms/wapbox load */
125 } StatusInfo;
126 
127 /* create new SMS center connection from given configuration group,
128  * or return NULL if failed.
129  *
130  * The new connection does its work in its own privacy, and calls
131  * callback functions at bb_smscconn_cb module. It calls function
132  * bb_smscconn_ready when it has put everything up.
133  *
134  * NOTE: this function starts one or more threads to
135  * handle traffic with SMSC, and caller does not need to
136  * care about it afterwards.
137  */
138 SMSCConn *smscconn_create(CfgGroup *cfg, int start_as_stopped);
139 
140 /* shutdown/destroy smscc. Stop receiving messages and accepting
141  * new message to-be-sent. Die when any internal queues are empty,
142  * if finish_sending != 0, or if set to 0, kill connection ASAP and
143  * call send_failed -callback for all messages still in queue
144  */
145 void smscconn_shutdown(SMSCConn *smscconn, int finish_sending);
146 
147 /* this is final function to cleanup all memory still held by
148  * SMSC Connection after it has been killed (for synchronization
149  * problems it cannot be cleaned automatically)
150  * Call this after send returns problems or otherwise notice that
151  * status is KILLED. Returns 0 if OK, -1 if it cannot be (yet) destroyed.
152  */
154 
155 /* stop smscc. A stopped smscc does not receive any messages, but can
156  * still send messages, so that internal queue can be emptied. The caller
157  * is responsible for not to add new messages into queue if the caller wants
158  * the list to empty at some point
159  */
161 
162 /* start stopped smscc. Return -1 if failed, 0 otherwise */
164 
165 /* Return name of the SMSC, as reference - caller may not free it! */
167 
168 /* Return ID of the SMSC, as reference - caller may not free it! */
169 const Octstr *smscconn_id(SMSCConn *conn);
170 
171 /* Return Admin ID of the SMSC, as reference - caller may not free it! */
172 const Octstr *smscconn_admin_id(SMSCConn *conn);
173 
174 /* Check if this SMSC Connection is usable as sender for given
175  * message. The bearerbox must then select the good SMSC for sending
176  * according to load levels and connected/disconnected status, this
177  * function only checks preferred/denied strings and overall status
178  *
179  * Return -1 if not (denied or permanently down), 0 if okay,
180  * 1 if preferred one.
181  */
182 int smscconn_usable(SMSCConn *conn, Msg *msg);
183 
184 /* Call SMSC specific function to handle sending of 'msg'
185  * Returns immediately, with 0 if successful and -1 if failed.
186  * In any case the caller is still responsible for 'msg' after this
187  * call
188  * Note that return value does NOT mean that message has been send
189  * or send has failed, but SMSC Connection calls appropriate callback
190  * function later
191  */
192 int smscconn_send(SMSCConn *smsccconn, Msg *msg);
193 
194 /* Return just status as defined below */
196 
197 /* return current status of the SMSC connection, filled to infotable.
198  * For unknown numbers, put -1. Return -1 if either argument was NULL.
199  */
200 int smscconn_info(SMSCConn *smscconn, StatusInfo *infotable);
201 
202 /* Determine if the specific SMS center group will be started
203  * with multiple instances.
204  * Return the number of multiple instances that should be started.
205  * If no multiple indicator is set in the config group, then 1
206  * is returned.
207  */
208 unsigned int smscconn_instances(CfgGroup *grp);
209 
210 /* Reconfigure the running SMSC for any routing relevant
211  * information from the configuration group.
212  */
213 void smscconn_reconfig(SMSCConn *conn, CfgGroup *grp);
214 
215 #endif
long online
Definition: smscconn.h:122
unsigned long received_dlr
Definition: smscconn.h:117
void smscconn_start(SMSCConn *smscconn)
Definition: smscconn.c:477
const Octstr * smscconn_name(SMSCConn *smscconn)
Definition: smscconn.c:493
smscconn_killed_t
Definition: smscconn.h:105
int smscconn_status(SMSCConn *smscconn)
Definition: smscconn.c:665
int smscconn_usable(SMSCConn *conn, Msg *msg)
Definition: smscconn.c:514
smscconn_status_t status
Definition: smscconn.h:113
smscconn_killed_t killed
Definition: smscconn.h:114
unsigned long sent_dlr
Definition: smscconn.h:119
long queued
Definition: smscconn.h:121
Definition: msg.h:79
unsigned long sent
Definition: smscconn.h:118
unsigned long failed
Definition: smscconn.h:120
int is_stopped
Definition: smscconn.h:115
smscconn_status_t
Definition: smscconn.h:96
int smscconn_send(SMSCConn *smsccconn, Msg *msg)
Definition: smscconn.c:596
void smscconn_shutdown(SMSCConn *smscconn, int finish_sending)
Definition: smscconn.c:378
int smscconn_stop(SMSCConn *smscconn)
Definition: smscconn.c:457
int load
Definition: smscconn.h:123
const Octstr * smscconn_id(SMSCConn *conn)
Definition: smscconn.c:500
static Cfg * cfg
Definition: smsbox.c:115
void smscconn_reconfig(SMSCConn *conn, CfgGroup *grp)
Definition: smscconn.c:704
Definition: octstr.c:118
Definition: cfg.c:73
unsigned int smscconn_instances(CfgGroup *grp)
Definition: smscconn.c:149
const Octstr * smscconn_admin_id(SMSCConn *conn)
Definition: smscconn.c:507
int smscconn_destroy(SMSCConn *smscconn)
Definition: smscconn.c:406
unsigned long received
Definition: smscconn.h:116
struct smsc_state StatusInfo
SMSCConn * smscconn_create(CfgGroup *cfg, int start_as_stopped)
Definition: smscconn.c:162
static XMLRPCDocument * msg
Definition: test_xmlrpc.c:86
int smscconn_info(SMSCConn *smscconn, StatusInfo *infotable)
Definition: smscconn.c:673
See file LICENSE for details about the license agreement for using, modifying, copying or deriving work from this software.