sjero.net Git - linphone/blob - coreapi/sal.h

   1 /*
   2 linphone
   3 Copyright (C) 2010  Simon MORLAT (simon.morlat@free.fr)
   4
   5 This program is free software; you can redistribute it and/or
   6 modify it under the terms of the GNU General Public License
   7 as published by the Free Software Foundation; either version 2
   8 of the License, or (at your option) any later version.
   9
  10 This program is distributed in the hope that it will be useful,
  11 but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 GNU General Public License for more details.
  14
  15 You should have received a copy of the GNU General Public License
  16 along with this program; if not, write to the Free Software
  17 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  18 */
  19
  20 /**
  21  This header files defines the Signaling Abstraction Layer.
  22  The purpose of this layer is too allow experiment different call signaling
  23  protocols and implementations under linphone, for example SIP, JINGLE...
  24 **/
  25
  26 #ifndef sal_h
  27 #define sal_h
  28
  29 #include "mediastreamer2/mscommon.h"
  30
  31 struct Sal;
  32
  33 typedef struct Sal Sal;
  34
  35 struct SalOp;
  36
  37 typedef struct SalOp SalOp;
  38
  39 struct SalAddress;
  40
  41 typedef struct SalAddress SalAddress;
  42
  43 /* Address manipulation API*/
  44 SalAddress * sal_address_new(const char *uri);
  45 SalAddress * sal_address_clone(const SalAddress *addr);
  46 const char *sal_address_get_scheme(const SalAddress *addr);
  47 const char *sal_address_get_display_name(const SalAddress* addr);
  48 const char *sal_address_get_username(const SalAddress *addr);
  49 const char *sal_address_get_domain(const SalAddress *addr);
  50 void sal_address_set_display_name(SalAddress *addr, const char *display_name);
  51 void sal_address_set_username(SalAddress *addr, const char *username);
  52 void sal_address_set_domain(SalAddress *addr, const char *host);
  53 void sal_address_set_port(SalAddress *addr, const char *port);
  54 void sal_address_set_port_int(SalAddress *uri, int port);
  55 void sal_address_clean(SalAddress *addr);
  56 char *sal_address_as_string(const SalAddress *u);
  57 char *sal_address_as_string_uri_only(const SalAddress *u);
  58 void sal_address_destroy(SalAddress *u);
  59
  60
  61
  62
  63 Sal * sal_init();
  64 void sal_uninit(Sal* sal);
  65 void sal_set_user_pointer(Sal *sal, void *user_data);
  66 void *sal_get_user_pointer(const Sal *sal);
  67
  68 typedef enum {
  69         SalTransportDatagram,
  70         SalTransportStream
  71 }SalTransport;
  72
  73 typedef enum {
  74         SalAudio,
  75         SalVideo,
  76         SalOther
  77 } SalStreamType;
  78
  79 typedef enum{
  80         SalProtoUnknown,
  81         SalProtoRtpAvp,
  82         SalProtoRtpSavp
  83 }SalMediaProto;
  84
  85 typedef struct SalEndpointCandidate{
  86         char addr[64];
  87         int port;
  88 }SalEndpointCandidate;
  89
  90 #define SAL_ENDPOINT_CANDIDATE_MAX 2
  91
  92 typedef struct SalStreamDescription{
  93         SalMediaProto proto;
  94         SalStreamType type;
  95         char addr[64];
  96         int port;
  97         MSList *payloads; //<list of PayloadType
  98         int bandwidth;
  99         int ptime;
 100         SalEndpointCandidate candidates[SAL_ENDPOINT_CANDIDATE_MAX];
 101 } SalStreamDescription;
 102
 103 #define SAL_MEDIA_DESCRIPTION_MAX_STREAMS 4
 104
 105 typedef struct SalMediaDescription{
 106         int refcount;
 107         char addr[64];
 108         char username[64];
 109         int nstreams;
 110         SalStreamDescription streams[SAL_MEDIA_DESCRIPTION_MAX_STREAMS];
 111 } SalMediaDescription;
 112
 113 SalMediaDescription *sal_media_description_new();
 114 void sal_media_description_ref(SalMediaDescription *md);
 115 void sal_media_description_unref(SalMediaDescription *md);
 116 bool_t sal_media_description_empty(SalMediaDescription *md);
 117 const SalStreamDescription *sal_media_description_find_stream(const SalMediaDescription *md,
 118     SalMediaProto proto, SalStreamType type);
 119
 120 /*this structure must be at the first byte of the SalOp structure defined by implementors*/
 121 typedef struct SalOpBase{
 122         Sal *root;
 123         char *route; /*or request-uri for REGISTER*/
 124         char *contact;
 125         char *from;
 126         char *to;
 127         char *origin;
 128         SalMediaDescription *local_media;
 129         SalMediaDescription *remote_media;
 130         void *user_pointer;
 131 } SalOpBase;
 132
 133
 134 typedef enum SalError{
 135         SalErrorNoResponse,
 136         SalErrorProtocol,
 137         SalErrorFailure, /* see SalReason for more details */
 138         SalErrorUnknown
 139 } SalError;
 140
 141 typedef enum SalReason{
 142         SalReasonDeclined,
 143         SalReasonBusy,
 144         SalReasonRedirect,
 145         SalReasonTemporarilyUnavailable,
 146         SalReasonNotFound,
 147         SalReasonDoNotDisturb,
 148         SalReasonMedia,
 149         SalReasonForbidden,
 150         SalReasonUnknown
 151 }SalReason;
 152
 153 typedef enum SalPresenceStatus{
 154         SalPresenceOffline,
 155         SalPresenceOnline,
 156         SalPresenceBusy,
 157         SalPresenceBerightback,
 158         SalPresenceAway,
 159         SalPresenceOnthephone,
 160         SalPresenceOuttolunch,
 161         SalPresenceDonotdisturb,
 162         SalPresenceMoved,
 163         SalPresenceAltService,
 164 }SalPresenceStatus;
 165
 166 typedef enum SalSubscribeState{
 167         SalSubscribeActive,
 168         SalSubscribeTerminated
 169 }SalSubscribeState;
 170
 171 typedef void (*SalOnCallReceived)(SalOp *op);
 172 typedef void (*SalOnCallRinging)(SalOp *op);
 173 typedef void (*SalOnCallAccepted)(SalOp *op);
 174 typedef void (*SalOnCallAck)(SalOp *op);
 175 typedef void (*SalOnCallUpdated)(SalOp *op);
 176 typedef void (*SalOnCallTerminated)(SalOp *op, const char *from);
 177 typedef void (*SalOnCallFailure)(SalOp *op, SalError error, SalReason reason, const char *details);
 178 typedef void (*SalOnAuthRequested)(SalOp *op, const char *realm, const char *username);
 179 typedef void (*SalOnAuthSuccess)(SalOp *op, const char *realm, const char *username);
 180 typedef void (*SalOnRegisterSuccess)(SalOp *op, bool_t registered);
 181 typedef void (*SalOnRegisterFailure)(SalOp *op, SalError error, SalReason reason, const char *details);
 182 typedef void (*SalOnVfuRequest)(SalOp *op);
 183 typedef void (*SalOnDtmfReceived)(SalOp *op, char dtmf);
 184 typedef void (*SalOnRefer)(Sal *sal, SalOp *op, const char *referto);
 185 typedef void (*SalOnTextReceived)(Sal *sal, const char *from, const char *msg);
 186 typedef void (*SalOnNotify)(SalOp *op, SalSubscribeState ss, SalPresenceStatus status, const char *msg);
 187 typedef void (*SalOnSubscribeReceived)(SalOp *salop, const char *from);
 188 typedef void (*SalOnSubscribeClosed)(SalOp *salop, const char *from);
 189 typedef void (*SalOnInternalMsg)(Sal *sal, const char *msg);
 190 typedef void (*SalOnPingReply)(SalOp *salop);
 191
 192 typedef struct SalCallbacks{
 193         SalOnCallReceived call_received;
 194         SalOnCallRinging call_ringing;
 195         SalOnCallAccepted call_accepted;
 196         SalOnCallAck call_ack;
 197         SalOnCallUpdated call_updated;
 198         SalOnCallTerminated call_terminated;
 199         SalOnCallFailure call_failure;
 200         SalOnAuthRequested auth_requested;
 201         SalOnAuthSuccess auth_success;
 202         SalOnRegisterSuccess register_success;
 203         SalOnRegisterFailure register_failure;
 204         SalOnVfuRequest vfu_request;
 205         SalOnDtmfReceived dtmf_received;
 206         SalOnRefer refer_received;
 207         SalOnTextReceived text_received;
 208         SalOnNotify notify;
 209         SalOnSubscribeReceived subscribe_received;
 210         SalOnSubscribeClosed subscribe_closed;
 211         SalOnInternalMsg internal_message;
 212         SalOnPingReply ping_reply;
 213 }SalCallbacks;
 214
 215 typedef struct SalAuthInfo{
 216         char *username;
 217         char *userid;
 218         char *password;
 219         char *realm;
 220 }SalAuthInfo;
 221
 222 void sal_set_callbacks(Sal *ctx, const SalCallbacks *cbs);
 223 int sal_listen_port(Sal *ctx, const char *addr, int port, SalTransport tr, int is_secure);
 224 void sal_set_user_agent(Sal *ctx, const char *user_agent);
 225 void sal_use_session_timers(Sal *ctx, int expires);
 226 int sal_iterate(Sal *sal);
 227 MSList * sal_get_pending_auths(Sal *sal);
 228
 229 /*create an operation */
 230 SalOp * sal_op_new(Sal *sal);
 231
 232 /*generic SalOp API, working for all operations */
 233 Sal *sal_op_get_sal(const SalOp *op);
 234 void sal_op_set_contact(SalOp *op, const char *contact);
 235 void sal_op_set_route(SalOp *op, const char *route);
 236 void sal_op_set_from(SalOp *op, const char *from);
 237 void sal_op_set_to(SalOp *op, const char *to);
 238 void sal_op_release(SalOp *h);
 239 void sal_op_authenticate(SalOp *h, const SalAuthInfo *info);
 240 void sal_op_set_user_pointer(SalOp *h, void *up);
 241 int sal_op_get_auth_requested(SalOp *h, const char **realm, const char **username);
 242 const char *sal_op_get_from(const SalOp *op);
 243 const char *sal_op_get_to(const SalOp *op);
 244 const char *sal_op_get_contact(const SalOp *op);
 245 const char *sal_op_get_route(const SalOp *op);
 246 const char *sal_op_get_proxy(const SalOp *op);
 247 /*for incoming requests, returns the origin of the packet as a sip uri*/
 248 const char *sal_op_get_network_origin(const SalOp *op);
 249 void *sal_op_get_user_pointer(const SalOp *op);
 250
 251 /*Call API*/
 252 int sal_call_set_local_media_description(SalOp *h, SalMediaDescription *desc);
 253 int sal_call(SalOp *h, const char *from, const char *to);
 254 int sal_call_notify_ringing(SalOp *h);
 255 int sal_call_accept(SalOp*h);
 256 int sal_call_decline(SalOp *h, SalReason reason, const char *redirection /*optional*/);
 257 SalMediaDescription * sal_call_get_final_media_description(SalOp *h);
 258 int sal_refer(SalOp *h, const char *refer_to);
 259 int sal_call_send_dtmf(SalOp *h, char dtmf);
 260 int sal_call_terminate(SalOp *h);
 261 bool_t sal_call_autoanswer_asked(SalOp *op);
 262
 263 /*Registration*/
 264 int sal_register(SalOp *op, const char *proxy, const char *from, int expires);
 265 int sal_unregister(SalOp *h);
 266
 267 /*Messaging */
 268 int sal_text_send(SalOp *op, const char *from, const char *to, const char *text);
 269
 270 /*presence Subscribe/notify*/
 271 int sal_subscribe_presence(SalOp *op, const char *from, const char *to);
 272 int sal_unsubscribe(SalOp *op);
 273 int sal_subscribe_accept(SalOp *op);
 274 int sal_subscribe_decline(SalOp *op);
 275 int sal_notify_presence(SalOp *op, SalPresenceStatus status, const char *status_message);
 276 int sal_notify_close(SalOp *op);
 277
 278 /*presence publish */
 279 int sal_publish(SalOp *op, const char *from, const char *to, SalPresenceStatus status);
 280
 281
 282 /*ping: main purpose is to obtain its own contact address behind firewalls*/
 283 int sal_ping(SalOp *op, const char *from, const char *to);
 284
 285 #define payload_type_set_number(pt,n)   (pt)->user_data=(void*)((long)n);
 286 #define payload_type_get_number(pt)             ((int)(long)(pt)->user_data)
 287
 288 /*misc*/
 289 void sal_get_default_local_ip(Sal *sal, int address_family, char *ip, size_t iplen);
 290
 291
 292 /*internal API */
 293 void __sal_op_init(SalOp *b, Sal *sal);
 294 void __sal_op_set_network_origin(SalOp *op, const char *origin /*a sip uri*/);
 295 void __sal_op_free(SalOp *b);
 296
 297
 298 #endif