M2Msoft SIP CSDK
Transcription
M2Msoft SIP CSDK
GIMS SDK et Couche SIP Manuel de développement Langage C Réference : Version : Date : GIMS-CSDK-SIP-ManuelUtilisateur-FR 1.01 15/08/2006 © 2004, 2006 M2MSOFT, Tous droits réservés. Aucune partie de ce document ne peut être reprise ou reproduite sous quelque forme que ce soit ni stockées en base de données ou dans tous systèmes de consultation sans le consentement écrit de M2MSOFT. Les produits mentionnés sont sujets à modifications sans avertissement. M2MSOFT Cap Delta, Parc Technologique Delta Sud, 09340 Verniolle, France Tél/fax : +33 561 69 00 85/08 – Email : [email protected] RCS Foix 448716001 - APE 722A http://www.m2msoft.com I S OMMAIRE I SOMMAIRE............................................................................................................................................ 2 II INTRODUCTION................................................................................................................................... 5 III PRESENTATION DE LA PILE DE PROTOCOLES GIMS............................................................. 6 G.I.M.S.........................................................................................................................................................6 IV PRESENTATION DU KIT GIMS-SIP-CSDK ...................................................................................7 P LATEFORMES SUPPORTEES ...........................................................................................................................7 COMPOSITION DU KIT .....................................................................................................................................7 V INSTALLATION SUR LINUX .............................................................................................................. 9 VI GUIDE DE DEVELOPPEMENT ..................................................................................................... 10 CINEMATIQUE D ’APPEL SIP.......................................................................................................................... 10 P RINCIPES ...................................................................................................................................................10 A PPLICATION S AMPLE1 ............................................................................................................................... 11 LES INCLUDES ............................................................................................................................................. 11 L A VERIFICATION DE LA LICENCE ................................................................................................................. 11 L A DECLARATION ET L'ARMEMENT DE LA FONCTION CALLBACK POUR LA SIGNALISATION SIP ........................ 12 L A BOUCLE D'EVENEMENTS .......................................................................................................................... 12 L A RECEPTION D'EVENEMENTS ..................................................................................................................... 13 COMMANDES ENVOYEES POUR LE CONTROLE D’ APPELS ................................................................................. 13 VII MANUEL DE REFERENCE ............................................................................................................ 15 LIBRAIRIE M2MUTIL ................................................................................................................................. 15 E VENEMENTS .............................................................................................................................................. 16 LIBRAIRIE SIP ............................................................................................................................................. 19 Gestion des UA ....................................................................................................................................... 19 Gestion des appels................................................................................................................................... 21 Type sipClient_t ...................................................................................................................................... 22 Type sipData_t ........................................................................................................................................ 22 Type Codec_t .......................................................................................................................................... 23 2 – GIMS CSDK SIP M2MSOFT 3 – GIMS CSDK SIP M2MSOFT Nous vous remercions d'avoir choisi de travailler avec les produits M2MSOFT. Si une partie de document était imprécise ou erronée ou encore que vous ayez des remarques et appréciations à formuler sur ce manuel, nous serons heureux de vous apporter une réponse personnalisée et de faire évoluer ce document. Nous vous remercions d'adresser vos remarques à : M2MSOFT Service Clients Cap Delta Parc Technologique Delta Sud 09340 VERNIOLLE ou [email protected] en mentionnant la référence de ce manuel: GIMS-CSDK-SIP-ManuelUtilisateur_FR_v1.01 4 – GIMS CSDK SIP M2MSOFT II INTRODUCTION Ce document présente la couche SIP et le kit de développement pour langage C destiné à la réalisation d'applications de voix et vidéo sur IP intégrant les technologies SIP, en particulier en plateforme embarquée. La version décrite dans ce document est destinée aux plates-formes LINUX et au développement en langage C. Les produits présentés ici font partie de la suite de kits de développements commercialisés par M2MSOFT. Ces produits sont la propriété exclusive de M2MSOFT et les droits attachés sont protégés par l'Agence pour la Protection des Programmes (APP, France). La couche protocolaire SIP et le kit de développement correspondant existent pour plusieurs platesformes, systèmes et langages, dont JAVA et C. Le lecteur est invité à contacter le service commercial de M2MSOFT ([email protected]) afin d'avoir la liste exhaustive des supports validés. Ce manuel n'est pas un manuel de référence ou une documentation sur SIP 2.0 et ses protocoles. Le lecteur désireux d'avoir une vue exhaustive de ces protocoles de communication se reportera aux documentations des standards RFC3261 et attenants Les informations dans ce document peuvent ne pas refléter l'état des kits au moment de la lecture. Le contenu réel des kits est amené à changer au fur et à mesure que de nouvelles fonctionnalités sont ajoutées. 5 – GIMS CSDK SIP M2MSOFT III P RESENTATION DE LA PILE DE PROTOCOLES GIMS G.I.M.S. M2MSOFTpropose la famille de produits « GIMS » (Global Ip Multimedia System) composée de couches logicielles et de serveurs prêt à l'emploi avec leurs interfaces de programmation. Ces produits sont destinés au développement et à l'exécution d'applications voix et vidéo sur IP en protocoles H323 et SIP. La fig.1. présente une vue de ces briques technologiques logicielles, utilisées dans tous les produits « serveurs » M2MSOFT: gestionnaire de communications (S5000), iPBX (S5000 Express), serveur audio, pont vidéo (A6000, C3000), etc. Certaines briques technologiques sont disponibles à la commercialisation séparée, pour la réalisation et l'intégration de produits industriels. C'est le cas des couches H323 et SIP de la famille appelée M2MStacks VoIP Kit. Fig.1. Aperçu des librairies GIMS 6 – GIMS CSDK SIP M2MSOFT IV P RESENTATION DU KIT GIMS-SIP-CSDK Le kit GIMS-SIP-CSDK est composé de librairies et de fichiers d'includes permettant l'intégration du protocole SIP 2.0 et des communications voIP au sein d'un applicatif utilisateur, en langage C. Ce kit permet : - l'encodage et le décodage de messages de signalisation conformes à SIP 2.0 RFC3261, RFC3265, RFC3515 - l'encodage et le décodage d’authentification RFC2617 / Digest MD5 - l’encodage et le décodage de DTMF au format INFO ou RFC2833 (RTP payload) - l'acceptation ou le rejet d'appels - la redirection d'appels - la gestion de plusieurs appels simultanés - le support de UDP, TCP, TLS 1.0 - le développement de clients, serveurs, proxy, registrar, etc NOTE: certaines fonctionnalités peuvent faire l'objet d'une licence particulière. NOTE: le kit existe également pour plate-forme JAVA (JVM 1.1 et supérieure). Plateformes supportées Processeur Plateforme Intel i386, PC 486, Pentium Système Linux Linux RedHat 6.2, 7.3, 9 Linux Fedora 1/2/3/4 Linux Enterprise 3/4 Linux Debian Linux Mandrake 9 Carte réseau Ethernet ARM9 VCMA9 de MPL AG Linux PPC MAC Linux Carte CPU PowerQuicc Compatibilité voIP (*) Pré-requis Kernel GNU- Linux pour VCMA9 Carte réseau Ethernet Swissvoice IP10 S Leadtek BVP8770 PA1688S chip Radvision GW ViaIP AudioCodes GW MP AudioCodes GW Median SJPhone Express Talk UtStarcom F1000 Wifi Linksys ip Phone SPA941 etc Linux From Scratch, Redhat Linux, Debian Carte réseau Ethernet (*) Liste non exhaustive Composition du kit Le kit GIMS-SIP-CSDK est composé des fichiers suivants : Fichiers Description Librairies /lib libsip.a Encodeurs/décodeurs libm2msiputil.a API utilisateur de contrôle événements/commandes Includes /include m2msiputil.h Fichiers de descriptions à inclure dans les applications. sip.h 7 – GIMS CSDK SIP M2MSOFT Fichiers Description lic.txt Fichier de licence, à éditer en fonction de votre plate-forme d'exécution et des informations fournies par M2MSOFT. Une licence non valide ne permettra pas à vos programmes de s'exécuter. sample1 (répertoire) Ce répertoire contient un exemple C et son Makefile. 8 – GIMS CSDK SIP M2MSOFT V INSTALLATION SUR LINUX La livraison est constitué d'un fichier archive compressé: GIMS-CSDK-SIP-VVV.tar.gz où VVV est la version produit. 1/ Ouvrir une fenêtre console Linux (sur le login utilisateur de votre choix, non nécessairement root) 2/ Choisir un emplacement pour le kit. (Par exemple vous êtes placés sur /home/tom si votre login est tom) Le chemin menant à cet emplacement sera appelé ROOTDIR par la suite. # tar xvfz GIMS-CSDK-SIP-VVV.tar.gz Le kit est installé, avec création du sous répertoire GIMS-CSDK-SIP-VVV. Le chemin complet incluant GIMS-CSDK-SIP-VVV est appelé ROOTDIR. (Par exemple, ROOTDIR symbolise /home/tom/GIMS-CSDK-SIP-VVV.) 3/ Paramétrage Makefile et compilation de l'exemple fourni Allez dans le répertoire de l'exemple sample1. # cd <ROOTDIR> # cd sample1 Edition du Compile. Plusieurs Makefile ‘Compile’ peuvent être présents. Sur plateforme intel, éditer « Compile » # vi Compile ou tout autre éditeur de fichier utilisé. Mettre à jour le chemin GCC vers le compilateur GNU-gcc Sauvegarder le fichier (<ESC> :wq <Entree> pour vi) Sur plateforme ARM9, éditer « Makefile.arm9 ». # vi Compile.arm9 ou tout autre éditeur de fichier utilisé. Mettre à jour le chemin GCC vers le compilateur croisé GNU-arm-gcc Sauvegarder le fichier (<ESC> :wq <Entree> pour vi) 4/ Compilation # sh ./Compile ou sh ./Compile.arm9 Aucune erreur ne doit se produire sur la sortie standard. Les chemins des includes et des librairies du kits sont indiqués en relatifs. En cas d 'erreur, vérifier la présence des fichiers contenus dans les répertoires <ROOTDIR>/lib et <ROOTDIT>/include. 5/ Exécution de l'exemple Placer l'exécutable ainsi obtenu (sample1) sur une zone d'exécution du processeur cible. L'exemple sample1 est un utilitaire de génération d'appel voIP. Au démarrage, sample1 se met en attente d'appels voIP et lance lui même un appel vers un téléphone ou softphone dont l'adresse IP est spécifiée dans le programme lui même. # ./sample1 Le fichier source sample1.c est à adapter en fonction de votre environnement. En particulier, l’adresse IP locale et celle du téléphone SIP à appeler sont à préciser. exemple: remplacer 192.168.8.9 par l'adresse IP d'un endpoint SIP accessible sur votre réseau. En fonction des événements de signalisation SIP/UDP, sample1 affiche des traces et messages. Erreur de lancement : si la licence n'est pas valide ou si le fichier lic.txt est absent, le programme ne se lancera pas. Contactez alors votre administrateur système ou M2MSOFT. 9 – GIMS CSDK SIP M2MSOFT VI GUIDE DE DEVELOPPEMENT Ce chapitre introduit le développement avec le kit au cours du parcours d'une application d'exemple (fournie en source avec le kit). Cinématique d’appel SIP Il est utilise de re-préciser ici les messages échangés lors d’un appel VoIP SIP (point à point ici) et les lieux d’intervention de l’API. Fig.2. Cinématique des échanges SIP L’API CSDK est associée à l’application utilisateur et permet : - de créer, encoder et envoyer sur le réseau les messages de la fig.2 - de détecter sur le réseau, décoder et présenter sous forme ‘lisible’ dans des structures de données, les messages de la fig.2 La partie média RTP/RTCP est basée sur UDP : cette partie peut être traitée via l’API :le développeur doit créer un socket UDP local afin de lire les données émanant du poste voIP distant et écrire les paquets voix à destination du téléphone IP. L’Api va remonter les informations dans des fonctions callBack de type processRTPMessage(remoteIp, remotePort, data, len), processRTCPMessage(remoteIp, remotePort, data, len). Principes Le kit SIP fonctionne par callback sur les différents messages de signalisations SIP 2.0 conformes au RFC3261, RFC3407, RFC3265, RFC3515. 10 – GIMS CSDK SIP M2MSOFT L'application utilisateur initialise le kit, arme des fonctions de traitements des événements et lance la boucle d'événements. Sur réception de messages réseaux voIP, les fonctions de traitements utilisateur sont appelées avec les paramètres des messages reçus. L'application utilisateur peut alors agir en construisant de nouveaux messages à destination d'autres systèmes, provoquant la poursuite des appels, leur redirection, leur rejet, le déclenchement de tout autre action, etc. NOTE: pour utiliser le kit SIP, vous devez obtenir une licence valide et appeler la méthode : checkLic() où options et info ont été communiqués par le support M2MSOFT. Application Sample1 Cet exemple utilise la signalisation SIP pour communiquer avec des téléphones IP et est livré en source dans la distribution. Objectifs de cet exemple: 1. Lancer un appel sortant vers un téléphone SIP 2. Faire sonner le téléphone 3. Détecter la sonnerie du poste 4. Détecter le décroché du poste 5. Gérer la négociation des codecs et canaux média 6. Détecter le raccroché du poste 7. Détecter une demande d'appel venant d'un poste voIP externe Les includes Cette partie présente la partie includes obligatoires et le formalisme pour démarrer une application. // to use SIP stack #include <sip.h> // C includes #include <stdio.h> #include <malloc.h> #include <string.h> sip.h sera inclut dans toutes vos applications utilisant le stack SIP. La vérification de la licence La fonction principale (main) doit débuter par la vérification de la licence. int main() { /* activate licence */ checkLic(1, "options string"); La vérification de la licence se fait par l'appel de checkLic() en passant en paramètres les valeurs communiquées par M2MSOFT lors de la commande. Attention, ces valeurs doivent correspondre et l'exécution s'opérer sur la plateforme associée à la licence. En cas de non correspondance, ou d'absence du fichier lic.txt sur disque, aucune exécution ne sera possible. 11 – GIMS CSDK SIP M2MSOFT La déclaration et l'armement de la fonction callback pour la signalisation SIP /** * Callback method for SIP events received. * evt is the event type * cli is the local SIP entity (UAS, UAC) that receives the data * data contains all the SIP event information */ void processSipEvent(int evt, sipClient_t *cli, sipData_t *data) { /* your code here */ } Toutes les fonctions « call back » sur la signalisation possèdent cette signature. Evt est le type d’événement survenu : initiation d’un dialogue SIP, code retour d’un appel, etc. Evt est lié à un message de signalisation SIP et l’espace data contient l’ensemble des champs du message en accès direct. /* within main */ /* prepare SIP events listener */ cli=new_sipClient(); // defines ourself setAlias(cli, “9999”); setConnectionType(cli, CONNECTION_TYPE_UDP); /* defines registrar access */ setDomain(cli, “192.168.0.30”); setDomainPort(cli, 5060); /* defines local listener*/ setLocalIpAddr(cli, “192.168.0.200”); setLocalPort(cli, 5060); setTTL(cli, 60); setLocalRTPPort(cli, 17512); setCodec(cli, CODEC_G711_ALAW); addSipListener(cli, processSipEvent); La figure ci-dessus est la préparation des données relatives à la définition d’un client (UAC) SIP. Sont définis un ensemble de paramètres tels les domaines SIP de ce client, ses codecs, TTL, et adresse IP, port d’écoute et émission local. Le callback SIP qui se mettra alors en écoute des messages de signalisation à destination de cette entité est défini par addSipListener(). Plusieurs clients (UAC) peuvent être définis et mis en écoute simultanément dans une même application, sur des ports et protocoles (UDP, TCP, TLS) différents. Lors de la gestion de plusieurs appels concurrents, en TCP, les écoutes sockets sont automatiquement ajoutées en début de dialogue et détruites en fin d’appel. La boucle d'événements En fin de programme principal, les actions de démarrage terminées, l’écoute sur les appels entrants étant armée, il faut activer la gestion de la signalisation par la couche SIP. La fonction 12 – GIMS CSDK SIP M2MSOFT processEvents() démarre les écoutes réseaux et appellera la ou les fonctions utilisateurs en cas de besoin. /* do not return */ processEvents(); La réception d'événements /** * SIP call back processing */ void processSipEvent(int evt, sipClient cli, sipData *data) { switch(evt){ /* * Notify user of the selected CODEC found within OK_INVITE. */ case CODEC_SELECTION : printf("Evt : %d, codec=%s, called=%s, callID=%s\n”, evt, data->getCodec(), data->getCallNumber(), data->getCallId()); // user code to add break; /* * Notify user of a call Release * */ case RELEASE : printf("Evt : %d, called=%s, callID=%s\n”, evt, data->getCallNumber(), data->getCallId()); // user code to add break; /* * Notify of an incoming call INVITE */ case CALL_RECEIVED : // user code Break ; /* etc */ } Les événements de signalisation SIP et de média RTP sont détaillés dans la partie manuel de référence de ce document. Commandes envoyées pour le contrôle d’appels A tout moment, dans les callbacks, dans des Threads, sur des événements externes (non nécessairement liés à SIP, IHM, etc), il est possible d’envoyer des actions telles que : - initier des appels - libérer des appels - envoyer des DTMF - envoyer des données dans la communication - envoyer des données de notification, pouvant être utilisées pour le suivi de présence ou d’état de endpoints (exemple du suivi de lignes dans un système PABX) 13 – GIMS CSDK SIP M2MSOFT - etc 14 – GIMS CSDK SIP M2MSOFT VII MANUEL DE REFERENCE Librairie M2MUTIL Cette librairie comprend un ensemble de fonctions générales liées au stack et aux communications, sans considérations de quels messages sont échangés. Méthode Signature Description checkLic() int checkLic(int channels, char Chargement de la licence du produit, à partir du fichier lic.txt *description) checkLicStr() int checkLicStr(int channels, char *description, char *lic) Chargement de la licence du produit, à partir de la clé lic passée en argument. new_sipClient() sipClient_t new_sipClient() Nouvelle structure pour une nouvelle entité SIP. halt_sipClient() void halt_sipClient(sipClient *c) Libère la mémoire associée au sipClient c addSipListener int addSipListener(sipClient_t Activation d’une écoute callback sur UDP ou TCP. La fonction callback f c, void (*f)(int x, sipClient_t est de la forme : *c, sipData_t *udata)) Int f(int x, sipClient_t *s, sipData_t *udata). Retourne -1 en cas d’echec sinon un entier >0. addRTPListener int addRTPListener(char *ip, int port, void (*f)(String remoteIp, int remotePort *c, char *rtpData, int len) ) Activation d’une écoute callback sur UDP, adresse locale ip et port local port. Retourne -1 en cas d’échec sinon un entier >0. removeListener() void removeListener(int fd) Dé-activation d’une écoute TCP ou UDP générique). Fd est la valeur obtenue lors du addSipListener(). allocateCallIdentifier() char *allocateCallIdentifier() Génération automatique d’une valeur de « callIIdentifier » pour les appels. allocateBranch() char *allocateBranch() Génération automatique d’une valeur de « branch » pour les VIA. allocateTag() char *allocateTag() Génération automatique d’une valeur de tag pour les FROM/TO des appels. getVersion() char *getVersion() Retourne la version du stack. setT1() void setT1(int t1) Fixe le timer de retransmission SIP, en ms. Pour les requetes INVITE en UDP. setT2() void setT2(int t2) Fixe le timer de retransmission SIP, en ms. Pour les requêtes NON INVITE et les réponses des INVITE, en UDP. processEvents() int processEvents() Boucle d’écoute d’événements de signalisation SIP. Appel automatique des callbacks. processEventsStop() int processEventsStop() Arrêt de la boucle d’événements. Sortie de processEvents(), avec -2 New_vector() vector new_vector() Gestion du type Vector, tableau dynamique. 15 – GIMS CSDK SIP M2MSOFT Méthode Signature Description Vector_addElement() void vector_addElement(vector v, int *e Ajout d’un élément e dans un tableau dynamique v. Vector_elementAt() int * vector_elementAt(vector v, int i) Lecture d’un élément en position I dans un tableau dynamique v. Vector_deleteElement() Destruction de l’élément e dans le void vector_deleteElement(vector v, vecteur v. int *e) Vector_deleteElementAt() Destruction de l’élément en position i void vector_deleteElementAt(vector dans le vecteur v. v, int i) Vector_size() int vector_size(vector v) RTPInit() RTPSrc_t *RTPInit(int SSRC, Initialise l’encodeur RTP. Définition char payloadType, int period) pour ce canal RTP, de l’identifiant de Retourne le nombre d’éléments dans le vecteur v. source SSRC (4 octets), du type de données –exemple G711ALAWet de ‘incrément de la valeur de timestamp RTP inter paquets. RTPEncode() char *RTPEncode(RTPSrc_t *s, char *buffer) Renseigne les 12 premiers octets de la zone passée en paramètre –data-, avec les valeurs à jour d’en-tête RTP. NOTE : l’appel à la licence checkLic() doit avoir été fait pour l’accès à ces fonctions RTP. RTPHalt() void RTPHalt(RTPSrc_t *s) Libére la mémoire associée à l’objet RTPSrc_t considéré. Evénements Le tableau ci-après détaille l’ensemble des événements remontés dans les callback de signalisation. Les champs utiles de l’objet sipData sont indiqués. Evénement CODEC_SELECTION Syntaxe int Notifie l'utilisateur du codec principal sélectionné lors du message OK_INVITE ou de l'acceptation d'un appel entrant (seuls les champs codec, callNumber et callId de l'objet sipData sont utilisés). RELEASE 16 – GIMS CSDK SIP Description Notifie l'utilisateur de la fin d'un appel (seuls les champs callId et callNumber de l'objet sipData sont utilisés). . M2MSOFT Evénement Syntaxe Description CALL_FAILED_CAUSE_N OT_REGISTERED Notifie l'utilisateur qu'il n'est pas possible d'établir un appel avec le distant sans être enregistré (seuls les champs callNumber et callId de l'objet sipData sont utilisés). CALL_FAILED_CAUSE_ MAX_LIC Notifie l'utilisateur qu'il n'est pas possible d'établir un appel avec le distant, le nombre d'appels autorisé par la licence est atteint (seuls les champs callNumber et callId de l'objet sipData sont utilisés). REMOTE_RTP_CONFIG Notifie l'utilisateur du port et de l'adresse IP (RTP) du distant (seule les champs ip, port, callId et callNumber de l'objet sipData sont utilisés). CALL_RECEIVED Notifie l'utilisateur qu'il reçoit un appel (seuls les champs callId et callNumber de l'objet sipData sont utilisés) RINGING Notifie l'utilisateur qu'un appel sortant est en sonnerie (seuls les champs callId, callNumber et callIn de l'objet sipData sont utilisés). INFO Notifie l'utilisateur qu'il a reçu un message de type INFO (seuls les champs callId, callNumber et data de l'objet sipData sont utilisés). NOTIFY Notifie l'utilisateur qu'il a reçu un message de type NOTIFY (seuls les champs callId et data de l'objet sipData sont utilisés). OK_REGISTER Notifie l'utilisateur que l'enregistrement au serveur registrar est accepté (seul le champ code de l'objet sipData est utilisé). 17 – GIMS CSDK SIP M2MSOFT Evénement Syntaxe Description OK_INFO Notifie l'utilisateur qu'il a reçu un message ok suite à un message de type INFO (seuls les champs callId et code de l'objet sipData sont utilisés). OK_INVITE Notifie l'utilisateur que l'appel est décroché (seuls les champs callId, code et callNumber de l'objet sipData sont utilisés). OK_BYE Notifie l'utilisateur qu'il a reçu un message ok suite à un message de type BYE (seuls les champs callId et code de l'objet sipData sont utilisés). OK_CANCEL Notifie l'utilisateur qu'il a reçu un message ok suite à un message de type CANCEL (seuls les champs callId et code de l'objet sipData sont utilisés). OK_SUBSCRIBE : Notifie l'utilisateur qu'il a reçu un message ok suite à un message de type SUBSCRIBE (seuls les champs callId et code de l'objet sipData sont utilisés). KO_REGISTER : Notifie l'utilisateur qu'il n'est pas possible de s'enregistrer au serveur registrar (seul le champ code de l'objet sipData est utilisé). KO_INFO : Notifie l'utilisateur qu'il a reçu un message d'erreur suite à un message de type INFO (seuls les champs callId et code de l'objet sipData sont utilisés). KO_INVITE Notifie l'utilisateur que l'appel ne peut être établi (seuls les champs callId, code et callNumber de l'objet sipData sont utilisés). KO_BYE Notifie l'utilisateur qu'il a reçu un message d'erreur suite à un message de type BYE (seuls les champs callId et code de l'objet sipData sont utilisés). 18 – GIMS CSDK SIP M2MSOFT Evénement Syntaxe Description KO_CANCEL Notifie l'utilisateur qu'il a reçu un message d'erreur suite à un message de type CANCEL (seuls les champs callId et code de l'objet sipData sont utilisés). KO_SUBSCRIBE Notifie l'utilisateur qu'il a reçu un message d'erreur suite à un message de type SUBSCRIBE (seuls les champs callId et code de l'objet sipData sont utilisés). Librairie SIP Gestion des UA Méthode Signature Description getCodec Codec_t getCodec(sipClient_t *c) Récupération du premier codec fixé pour l’UA c setCodec() void setCodec(sipClient_t *c, Codec_t *codec) Définit le premier codec à utiliser pour les appels avec l’UA c. addCodec() void addCodec(sipClient_t *c, Codec_t *codec) Ajoute un codec à la liste supportées par l’UA c setCodecList void setCodecList(sipClient_t *c, Vector_t *codecList) Spécifie la liste des codecs à utiliser. codecList est un vecteur de Codec_t * getCodecList Vector_t *getCodecList(sipClient_t *c) Récupère la liste des codecs utilisés. codecList est un vecteur de Codec_t * new_Codec Codec_t *new_Codec(Vector_t *attr, int type, int port) Création d’un codec sur mesure. Le port peut être 0, dans le cas d’un seul canal média. halt_Codec void halt_Codec(Codect_t * c) Libération mémoire d’un codec c getConnectionType() char Lecture du type de connexion utilisé par getConnectionType(sipClient_t l’UA c. *c) Retourne : CONNECTION_TYPE_UDP CONNECTION_TYPE_TCP CONNECTION_TYPE_TLS setConnectionType() void Définit le type de connexion à utiliser pour setConnectionType(sipClien t_t les appels depuis l’UA c. c, char type) 19 – GIMS CSDK SIP M2MSOFT Méthode Signature Description getAlias() char *getAlias(sipClient_t *c) Lecture de l’alias associé à l’UA c. Alias est une forme URI sans domaine. (équivalent au E164 ou H323-ID de H323) setAlias() void setAlias(sipClient_t *c, char *alias) Définit l’alias de l’UA c. L’alias ne doit pas contenir de nom de domaine. setAccount() void setAccount(sipClient_t *c, Définition d’un compte, demandé par char *login, char *pwd) certains fournisseurs d’accès. Nom login et mot de passe pwd. Lors de la réception d’un UNAUTHORIZED sur l’enregistrement, l’enregistrement sera alors géré en accord avec les données du compte. getDomain() char *getDomain(sipClient_t *c) Lecture du nom de domaine (ou adresse IP) associé à l’UA c. La valeur retournée ne contient pas de port. Il s’agira de l’accès au REGISTRAR si les fonctions d’enregistrements sont utilisées. setDomain() void setDomain(sipClient_t *c, char *d) Définit le domaine de l’UA c. Ce domaine ne doit pas contenir de port. (le défaut 5060 sera appliqué) getDomainPort() int getDomainPort(sipClient_t *c) Lecture du port associé au domaine de l’UA c. La valeur retournée est le port UDP/TCP définit pour le domaine et sera pris pour joindre le serveur registrar si ces fonctions sont utilisées. setDomainPort() void setDomainPort(sipClient_t Définit le port UDP/TCP du domaine de *c, int dp) l’UA c. getLocalIPAddr() char * getLocalIpAddr(sipClient_t *c) Lecture de l’adresse IP locale de travail de l’UA c. Retourne NULL en cas d’erreur ou une chaine non vide. setLocalIPAddr() int setLocalIpAddr(sipClient_t *c, char *addr) Définit l’adresse locale de travail de l’UA c. Un socket UDP ou TCP sera attaché ici. Retourne -1 en cas d’erreur, 0 sinon getLocalPort() int getLocalPort(sipClient_t *c) Lecture du port local d’écoute de l’UA c. La valeur retournée est le port UDP/TCP utilisé par cet UA pour sa signalisation. setLocalPort() int setLocalPort(sipClient_t *c, int p) 20 – GIMS CSDK SIP M2MSOFT Définit le port UDP/TCP utilisé localement par l’UA c pour sa signalisation. Retourne -1 en cas d’erreur, 0 sinon Méthode getLocalRTP() Signature Description int getLocalRTP(sipClient_t *c) Lecture du port local d’écoute media de l’UA c. La valeur retournée est le port UDP/TCP utilisé par cet UA pour son écoute média et son émission média (symétrique). NOTE : 1 canal géré ici. La gestion de plusieurs canaux média peut se faire avec les méthodes addRTPListener(). setLocalRTP() int setLocalRTP(sipClient_t *c, int p) Définit le port (pair) UDP/TCP utilisé localement par l’UA c pour son média. Retourne -1 en cas d’erreur, 0 sinon Le port RTCP utilisé sera automatiquement p+1. getTTL() int getTTL(sipClient_t *c) setTTL() int setTTL(sipClient_t *c, int ttl) Définit le TTL en secondes, pour l’UA c. Dans le cas de l’usage d’un REGISTRAR, cette valeur est celle annoncée dans les REGISTER. Le développeur veillera a lancer des « registrations() » périodiques adaptées. L’usage d’un TTL à 0 est utilisé pour se ‘désenregistrer’. Lecture du TTL en secondes, associé à cet UA c. Dans le cas de l’usage d’un REGISTRAR, cette valeur est celle annoncée dans les REGISTER. Le développeur veillera a lancer des « registrations() » périodiques adaptées. Gestion des appels Méthode call Signature char *call(sipClient_t *c, char *calling, char *called) Description Appel sortant.Initiation d’un appel sortant vers le destinataire URI called. Calling permet de re-écrire le numéro appellant. Calling null force l’alias de l’UA c. Calling non null utilise cette valeur comme numéro source de l’appel. Retourne null en cas d’échec immédiat, sinon le callId de l’appel. release void release(char *callId) Demande la libération de l’appel /dialogue avec le callIdentifier callId. registration void registration(sipClient_t *cli) Demande d’enregistrement de l’UA cli auprès du registrar définit dans son domaine. 21 – GIMS CSDK SIP M2MSOFT Méthode Signature Description unregistration Void unregistration(sipClient_t Demande de désenregistrement *cli) immédiat de l’UA cli auprès du registrar définit dans son domaine. isRegistered char isRegistered(sipClient_t *c) Indique si l’UA c est actuellement enregsitrée auprès de son serveur REGISTRAR. Retourne 1 en cas de succès, sinon -1. reject void reject(char *callId, int code) Rejette l’appel entrant associé au callIdentifier callId. Code permet de spécifier le code de rejet. Par défaut : 0 génère un « Busy Here » accept void accept(char *calId) Décroché de l’appel en cours sur le callidentifier callId. Le codec définit sur l’UA c est utilisé. Info char info(char *callId, char *data, int len, char *contentType) Emission d’un message INFO sur le dialogue de callIdentifier callId. Le body envoyé est data et de longueur len. Les données ne subissent pas de traitement avant envoi sur le réseau. Un encodage si des données binaires sont à envoyer, est à prévoir dans l’application. ContentType permet de préciser le type de données envoyées (application/xml par exemple) Retourne -1 en cas d’erreur (hors contexte) ou 0 en cas de succès. subscribe char info(char *callId, char *data, int len, char *contentType) Emission d’un message SUBSCRIBE (hors dialogue INVITE) avec le callIdentifier callId. Le body envoyé est data et de longueur len. Les données ne subissent pas de traitement avant envoi sur le réseau. Un encodage si des données binaires sont à envoyer, est à prévoir dans l’application. ContentType permet de préciser le type de données envoyées (application/xml par exemple) Retourne -1 en cas d’erreur (hors contexte) ou 0 en cas de succès. Type sipClient_t Type opaque. Aucun attribut utilisable pour le développeur. Les fonctions de haut niveau sont à utiliser. Type sipData_t L’objet sipData est renseigné lors du passage d’événements callback. Le contenu de cet objet, est utilisé par l’application pour réagir contextuellement. La modification de son contenu permet également de faire des réponses particulières lors des accept() et reject(). Attribut getCallNumber() setCallNumber() 22 – GIMS CSDK SIP Type char *getCallNumber() void *setCallNumber(char Description Le numéro de téléphone du distant Change le numéro du distant par nb. M2MSOFT getCallId setCallId isCallIn *nb) char *getCallId() void *setCallId(char *cid) char *isCallIn() setCallIn getIp void setCallIn(char b) char *getIp() Le callidentifier du message reçu. Change le callId de l’appel Récupère le sens de l’appel 1 : appel en arrivée Change le sens de l’appel Lecture de l’adresse IP du distant. setIp void *setIp(char *ip) Change l’adresse IP du distant. getPort setPort getCodecList int getPort() void setPort(int p) Vector_t * getCodecList() getData void getData(char **buffer, int *len) Lecture du port RTP du distant Change le port RTP du distant Lecture de la liste des codecs du distant. Dans certains messages. Retour null si aucun codec n’est présent. Sinon retourne un Vector contenant des Codec_t * Récupère les données brute du body d’un message INFO ou SUBSCRIBE ou NOTIFY ou encore du SDP private dans tout message. En retour, buffer est alloué et renseigné, len est mis à jour avec le nombre d’octets chargés. Note : buffer est alloué par la fonction et devra être libéré par l’utilisateur. getCode int getCode() Retourne le code de réponse SIP reçu. Type Codec_t Ce type décrit une capacité, un codec pour le SDP. Les codecs courants sont précisés mais des codecs non standards peuvent aussi être décrits. Attribut _attributesList Type Vector_t * M/O M _type int M _port int O M : obligatoire O : optionnel 23 – GIMS CSDK SIP M2MSOFT Description Liste d’attribut nom=valeur Exemple: a=rtpmap:96 telephone-event ou a=fmtp :96 0-15 AUDIO ou VIDEOou APPLICATION ou DATA (RTP/AVP) UDP port à annoncer dans le SDP m= attribute. Si non precisé, sera associé au premier media décrit dans le SDP.