1 /* ==================================================================== 2 * The Kannel Software License, Version 1.0 3 * 4 * Copyright (c) 2001-2014 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 { 97 SMSCCONN_CONNECTING, 98 SMSCCONN_ACTIVE, 99 SMSCCONN_ACTIVE_RECV, 100 SMSCCONN_RECONNECTING, 101 SMSCCONN_DISCONNECTED, 102 SMSCCONN_DEAD /* ready to be cleaned */ 103 } smscconn_status_t; 104 105 typedef enum { 106 SMSCCONN_ALIVE = 0, 107 SMSCCONN_KILLED_WRONG_PASSWORD = 1, 108 SMSCCONN_KILLED_CANNOT_CONNECT = 2, 109 SMSCCONN_KILLED_SHUTDOWN = 3 110 } smscconn_killed_t; 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 */ 153 int smscconn_destroy(SMSCConn *smscconn); 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 */ 160 int smscconn_stop(SMSCConn *smscconn); 161 162 /* start stopped smscc. Return -1 if failed, 0 otherwise */ 163 void smscconn_start(SMSCConn *smscconn); 164 165 /* Return name of the SMSC, as reference - caller may not free it! */ 166 const Octstr *smscconn_name(SMSCConn *smscconn); 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 */ 195 int smscconn_status(SMSCConn *smscconn); 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 203 #endif 204