VideoSMS/Client Application Programming Interface ... - MCTel

Stan, Hercegovačka ulica, Zagreb3. PRIKAZ OBJEKTA4

ContentsINDEXEXAMPLES3–1 Structure SMSMessage 3–13–2 SMSSession structure 3–23–3 Structure SMSUserAccountInfo 3–33–4 Structure SMSChargingData 3–43–5 SMSReport structure 3–53–6 SMSUserLocation structure 3–53–7 WapData structure 3–73–8 SMSOperator structure 3–73–9 SMSHandset structure 3–83–10 Structure SmsDateTimeType 3–89–1 Visual Basic SMS send example 9–19–2 C SMS Send sample progral 9–8vi

PrefacePublicThis manual is destined to programmers wishing to integrate theVideoSMS Client API functions in their computer applications.Document structureThis manual includes three chaptersOther documents on SMS and VideoSMSThis manual is part of the VideoSMS documentation. VideoSMS is anintegrated mobile messaging and server solution allowing the sendingof SMS, the checking of their successful transmission, the building ofPremium SMS applications with high value added contents.Other manuals of the VideoSMS documentation include:• General information about SMS is presented in the VideoSMS SMSWhitepaper.• the manuals of the client/server SMS interface and development tools:5 The FTP/XML Interface is described in the VideoSMS FTP/XMLInterface Manual.5 The HTTP/HTML Web Interface is described in the VideoSMSHTTP/HTML Interface Manual).5 additional information on the development of SMS applications isspecified in the guide How to develop with VideoSMS Interfacesand API.• the VideoSMS/Gateway SMS server and messaging platform hasits own complete documentation set (installation, management,development tools).Advanced technical informations regarding SMS and GSM standards arespecified in ETSI standards. The knownledge of these documents is notnecessary to use VideoSMS, interested persons may for example refer to:• Recommandation ETSI ETS 300 133-3: «Electromagnetic compatibilityand Radio Spectrum Matters (ERM); Enhanced Radio MEssage System(ERMES); Part 3: Network Aspects».• Recommandation ETSI GSM 03.40: «Digital cellulartelecommunications system (Phase 2+) Technical realization of theShort Message Service (SMS) Point-to-Point (PP)».• Recommandation ETSI GSM 07.05: «Digital cellulartelecommunications system (Phase 2+) Use of Data TerminalEquipment - Data Circuit terminating; Equipment (DTE-DCE)v

Prefaceinterface for Short Message Service (SMS) and Cell Broadcast Service(CBS).».• Recommandation ETSI ES 202 060-1: «Short Message Service (SMS)for fixed networks: Network Based Solution (NBS); Part 1: Overview».AbbreviationsIn this document, the following abbrevations are used:• SMS: Short Message Service• SMS-MO (Mobile Originated): SMS sent by a mobile user.• SMS-MT (Mobile Terminated): SMS sent to a mobile user.TrademarksSupportVIDEOSMS, SMSFAX, VIDEONET, VIDEONET/DEV-API, VIDEOMAIL,VIDEOCOM, VIDEOMASK, VIDÉOTELEX, VIDÉOTELEFAX,VIDEOTELETEX, VIDEOSCREEN, VIDEOSEC, WEBACCESS,VIDEOVALID, VIDEOBASE, VIDEOPAD, MONACO TELEMATIQUEMC-TEL, the MC-TEL logo are registered trademarks of MonacoTelematique MCTEL.All remarks and requests for information or support regarging VideoSMSsolutions and the worldwide SMS hosting center of MCTEL must beaddressed to:MONACO TELEMATIQUE MC-TEL,P.O. Box 225,98004 MONTE-CARLO CEDEXMONACOPhone: (+377)9216.8888Telex: MC 489.288Fax: (+377)9216.8865Web: http://www.mctel.fr and http://www.smsfax.comEmail (support): sms@mctel.frEmail (sales): sales@mctel.frMonaco Telematique MCTEL products and services include:• mobile (SMS, MMS, WAP) software (VideoSMS) and gateways.• worldwide SMS hosting center.• Fax gateways (VideoTelefax), telex gateways (Vidéotélex), pagers(VideoAlphaPage).• Videotex servers (VidéoNet) and gateways (VTX/Gate), multimediaservers (EuroVemmi).• Advanced firewall solutions (WebAccess).vi

1Introduction1.1 Integrating SMS features in computer applicationsWith VIDEOSMS software set, Monaco Telematique MCTEL offers acomplete solution to easily integrate SMS technology to offer to yourcustomers and users advanced applications that could be reached from anymobile phone, anywhere, anytime.The VideoSMS Application Programming Interface (API) functions ofcourse offer push-SMS features (such send SMS, send Wap Push SMS,check status of SMS sent), but they also allow to access very advancedfeatures, for example:• management of incoming SMS and Premium SMS, allowing to buildhigh value added SMS applications.• management of a SMS session context for multiple SMS transactionalapplications.• user location (geographical positioning).• mobile handset information retrieval.• accounting and management features.• and so on.Those functions are easy to use and to integrate in existing computerapplications, to be linked with the VideoSMS libraries or DLL.Please refer to the VideoSMS SMS Whitepaper for a complete introductionregarding SMS and the application you could build to take fully advantageof this new communication media.1.2 VIDEOSMS/Client Application Programming InterfaceIn order to be able to send SMS, a SMS Gateway must be connected andinterwork will the mobile operator networks. Such configuration is veryexpensive and incurs very high networking and infrastructure costs.In most cases, it is much efficient and cost-effective to use the worldwideMCTEL SMS shared hosting center to transmit SMS: in this case the freeVideoSMS/Client API is used to connect to MCTEL SMS Gateway and toexchange SMS messages. The only requirement for the calling system is tobe able to connect to the MCTEL SMS gateway through TCP/IP Internetor X.25 network and no fixed networking costs or infrastructure is needed,as all the mobile network connectivity is taken in charge by the MCTELSMS shared hosting center.1–1

IntroductionThe VIDEOSMS/Client API may be downloaded free of charge fromhttp://www.smsfax.com. Other free tools are also available, including:• HTTP/HTML Web interface, allowing to perform SMS operations bycalling Web cgi on the MCTEL SMS shared hosting center. Thisinterface is described in the VideoSMS HTTP/HTML InterfaceManual.• FTP/XML file interface, allowing to send SMS by creating and sendingby FTP to the MCTEL SMS shared hosting center a XML text filedescribing the SMS to be transmitted. This interface is described inthe VideoSMS FTP/XML Interface Manual.• SMTP email interface.• SMPP and UCP client/server access for large accounts.However this solution is completely flexible and your could anytimepurchase a VideoSMS gateway from MCTEL, in order to operate yourselfyour own SMS gateway, running on a system in your premises whereVideoSMS Gateway has been installed. Your system must be connectedand interwork with all mobile networks operators or internationalgateways needed for your application. That means that networking andinfrastructure costs are to be taken in account.1–2

2Using the Application Programming Interface2.1 IntroductionThe SMS functions could be easily be called from any compiledprogramming application allowing to create push-SMS applications andthe development of advanced Premium interactive SMS applications.The VideoSMS/Client API functions allows to access all VideoSMS featuresfrom most platforms accessing the MCTEL international shared hostinggateway in client/server mode. Supported platforms include:• Unix:5 Linux5 HP-UX5 HP/Compaq/Digital True64 Unix (Alpha)5 IBM AIX5 UNIX-SCO5 Sun Solaris• Windows• OpenVMS (VAX, Alpha, Itanium)• PalmOSThose functions are documented in the next chapter. A brief list of theavailable functions is given below.2.2 DistributionThe VideoSMS/Client API is supplied on CD-ROM to MCTELcustomers under contract and could be downloaded free of charge fromwww.smsfax.com2.2.1 WindowsThe Windows VIDEOSMS/Client API includes the following files:• smsApi.dll DLL.• smsApi.h C/C++ include file.• smsApi.lib C/C++ link file.• smsApi.tlb Visual Basic type definitions file.• example files (DemoSMSAPI.vbp, DemoSMSAPI.vbw, Form1.frm,DemoSMSAPI.exe)2–1

Using the Application Programming Interface2.2.2 UnixThe Unix VIDEOSMS/Client API includes the following files:• smsApi.o library.• smsApi.h include file.• examples files.2.2.3 Environnement OpenVMSThe OpenVMS VideoSMS/Client API is available for all OpenVMSenvironments:• VAX.• Alpha.• Itanium.It includes:• VIDEOSMSCLIENT.OLB library.• example programs: TEST_SMSCLIENT.EXE, TEST_SMSCLIENT.BAS• LINK_VIDEOSMSCLIENT.COM link procedure.2.3 Constant definitionsConstant definitions (error codes, and so on) are defined in .h include files.(messages d’erreurs, etc...)Link and build files are supplied.2.3.1 Networking functionsThose functions are used to establish, manage and release the linkbetween the MCTEL SMS shared host gateway:• SMS_ConnectGateway: establish link to MCTEL SMS gateway.• SMS_LoginGateway: application authentication on MCTEL SMSgateway.• SMS_LogoutGateway: logoff from MCTEL SMS Gateway.• SMS_DisconnectGateway: disconnect from MCTEL SMS gateway.• SMS_EnquireLink: check link state with MCTEL SMS gateway andreset inactivity timer.2–2

Using the Application Programming InterfacePlease note that MCTEL SMS hosting center will disconnect the linkto the calling client when an inactivity time expires (configured duringaccount creation, by default 1 minute). If the client application wishto remain connected without performing SMS operation (usually onlydone for high volume throughputs or when the application is to manageincoming SMS received), the application must call the SMS_EnquireLinkfunction at regular intervals before timer expiration to avoid beendisconnected.2.3.2 SMS transmission functionsThere is two kind of functions managing SMS communication withmobiles, they could be both used in the same application:• Function in non-session mode, for example used to send unsolicitedpush-SMS:5 SMS_Send: send an unsolicited SMS-MT (push-SMS) to the givenrecipient. This routine is not to be used to answer a request SMS-MO during a Premium SMS transaction, use instead the SMS_Reply function.5 SMS_PushWap: request to push a Wap URL by SMS to thegiven user, for example to transmit a ringtone, picture orexecutable content to the mobile, or to allow the mobile to connectautomatically to a Wap service.5 SMS_GetMessage: real-time receiving on open transmissionchannel of incoming SMS-MO or transmission acknowledgementsof previously submitted SMS-MT.5 SMS_ReadStatus: retrieve and return the state of a SMS whosetransmission request has been done previously.• Functions in session mode used to manage an interactive Premium ornon-Premium SMS transaction:5 SMS_Read: check for and return SMS-MO received for a givenapplication.5 SMS_GetSessionInfo: read the session data.5 SMS_GetSessionData: return session-specific informations andvariables previously saved using previous SMS_SaveSessionDatacalls during the same session.5 SMS_SaveSessionData: save session-specific variables relative tothe current session. Those variables will be available on requestduring the next SMS exchanges for this same session (with thesame user).5 SMS_Reply: send to the user a SMS-MT in reply to his request bySMS-MO, with or without closing the session. In most networks, itwill be nevertheless possible to send later unsolicited SMS-MT tothe same user using the SMS_Send function.2–3

Using the Application Programming Interface2.3.3 Other mobile functionsOther functions allows to perform specific operations, they may performdirectly specific requests over the mobile network and their use is thereforerestricted according to MCTEL contract and mobile network operatorspolicies and approval, availability vary account to countries:• GetLocation: retrieve mobile subscriber current or last knowngeographical location• FindOperator: returns the subscriber mobile network operator(including Network Country Code NCC and Mobile Network CodeMNC.• GetIMEI: retrieve either complete IMEI of the handset or only the TAC(Terminal Approval Code) according to user privilege.2.3.4 Management functionsManagement functions are available:• SMS_CreateAccount: create a new user account.• SMS_GetAccountInfo: retrieve user account data.• SMS_ModifyAccount: modify an existing user account.• SMS_IssueVoucher: issue a SMS voucher.• SMS_RedeemVoucher: cash a SMS voucher.• SMS_ResendPassword: send again its lost password to the user.• SMS_GetProcessedMessage: retrieve one per one all SMS messagessent.• SMS_GetAccountRecord: retrieve one per one all charging eventsoccured on this account.2.4 Link and build proceduresThey vary according to the platform used, please refer to the linkprocedures and examples supplied with the software distribution.2.5 WarningUsing the VideoSMS/Client functions and the MCTEL SMS Gatewaymay generate significative SMS communication costs, to the charge of thecompany SMS account should the SMS API be illegally used by an hackerhaving penetrated the system.It is therefore important to secure the access to the system used as SMSserver.2–4

Using the Application Programming InterfaceWe further recommand to use fixed TCP/IP address to call MCTEL SMSInternational Hosting Center and to transmit this TCP/IP address toMCTEL so we will configure our firewall to restrict access to this addressor to setup a Virtual Private Network (VPN) between the customernetwork and MCTEL network.Our customers are to fully comply with MCTEL code of conduct and theterms of their licence (e.g. prohibiting sending spam (unsolicited SMSmessages), sending offending content, and so on.).2–5

3SMS structures3.1 SMSMessageThe SMSMessage structure store the data relative to sent or receivedSMS.Example 3–1Structure SMSMessagetypedef struct{UInt32 messagetype;Char msg_reference_number[60];Char called_number[20];Char caller_number[20];Char alternate_number[20];UInt16 destPort;UInt16 srcPort;UInt32 msg_length;Uint32 msg_format;UInt32 msg_class;UInt32 msg_encoding;Uint32 msg_action;Uint32 msg_gsmflags;Uint32 msg_options;Uint32 country;Uint32 carrier;Uint32 sms_state;Uint32 sms_error;Uint32 credit_cost;SMSDateTime posted_date;char transmitted_date[18];SMSDateTime deferred_date;SMSDateTime expiration_date;Char sender_address[50];Char msg_data[500];} SMSMessage3.2 SMSSessionThe SMSSession store Premium SMS session data for interactive PremiumSMS applications. It is not used for simpler push-SMS applications.3–1

SMS structuresExample 3–2SMSSession structuretypedef struct{char sessionId[20];Char called_number[20];Char caller_number[20];char client_name[20];char application_name[50];UInt32 taxationRate;UInt32 current_exchange;UInt32 total_exchange;SMSDateTimeType Openeddatetime;SMSDateTimeType LastExchangedatetime;char latitude[8];char longitude[9);char price[8];} SMSSession3.3 Structure SMSUserAccountInfoThis structure is those of the user accounts managed by the VIDEOSMSGateway.It is for example used by SMS_CreateAccount and SMS_GetAccountInfofunctions.The time managed by this structure are internally stored using OpenVMSabsolute time format on a quadword (two 32 bits longwords).3–2

SMS structuresExample 3–3Structure SMSUserAccountInfotypedef struct{charcompany_userid[20];charclient_userid[20];charcompany_password[10];charclient_password[10];charcompany_name[40];charclient_name[20];charclient_surname[20];charaddress_1[80];charaddress_2[80];charaddress_3[80];charzip[10];charcity[40];charcountry[40];charmobile_number[16];charoffice_number[16];charfax_number[16];charemail_address[50];charcountry_prefix[4];chardriver_name[16];charnetwork_address[20];charrefereer[20];charsystem_type[20];charpromo_code[20];charnotification_address[50];charshortid[16];charreserved[326];Int32status_2;Int32smspremium_nbr;Int32CB_credit_amount_waiting;Int32CB_credit_units_waiting;Int32CB_credit_amount;Int32CB_credit_notok;Int32CB_credit_ok;Int32nbr_waiting_msg;Int32nbr_pwd_resend;uInt32inherit_value;Int32login_err;Int32nbr_access;Int32account_number;uInt32credits_account;uInt32spent_credits;uInt32date_open[2];uInt32date_close[2];uInt32last_connect[2];uInt32expiration_date[2];uInt32country_origin;uInt32carrier_number;uInt32transport_network;uInt32taxation_rate;uInt32total_sms_sent;uInt32total_sms_success;uInt32total_sms_received;uInt32total_mms_sent;uInt32total_mms_success;uInt32total_mms_received;uInt32total_fax_sent;uInt32total_fax_success;uInt32total_fax_received;uInt32total_telex_sent;uInt32total_telex_success;uInt32total_telex_received;uInt32status_bitarray;uInt32mobile_brand;uInt32mobile_type;uInt32mobile_capabilities;Example 3–3 Cont’d on next page3–3

SMS structuresExample 3–3 (Cont.)Structure SMSUserAccountInfoInt32 currency;Int32 user_language;Int32 default_charset;real double total_paid_amount;real double provider_paid_amount;} SMSUserAccountInfo3.4 Structure SMSChargingDataIt stores the charging information for messages exchanged.Example 3–4 Structure SMSChargingDatatypedef struct{Int32 type;Int32 flags;Int32 units;Int32 remaining_units;Uint32 reference;real double amount;SMSDateTime date;char info[10];} SMSChargingDataThe type variable may take the following value (odd: charging, even:credit):• 1: SMS charge: charging operation for a SMS-MT.• 2: SMS credit: SMS-MT credited back.• 3: read SMS charge: SMS-MO received.• 4: Minitel credit: account credit using videotex.• 5: SMS sent by Videotex: not charged as sent through Premiumvideotex service.• 7: Service message• 6: SMS+ credit: account credit using Premium SMS.• 8: CB credit: account credit using Credit Card.• 10: account credit by check.• 11: voucher emission (debited from user account).• 12: initial account credit at account creation• 14: manual account credit by accounting department• 16: account credit using a voucher.3–4

SMS structuresThe units value is positive when the account if credited, negative when itis charged.The remaining_units may be filled in or left to 0.3.5 SMSReportSMSReport structure store the data relative to SMS transmissionacknowledgements (successful transmission, error, and so on.)Example 3–5SMSReport structuretypedef struct{UInt32 report_type;UInt32 msg_reference_number;Char called_number[20];Char messageID[50];SmsDateTimeType timeStamp;} SMSReport3.6 SMSUserLocation structureThis structure allows to the user location positionning information.Example 3–6 SMSUserLocation structuretypedef struct{SmsDateTimeType age; /* age of location estimate */Uint32 type; /* location type */Uint32 shape; /* location shape */Uint32 cellid; /* Global Cell Identifier the user is attached to */char latitude[8]; /* latitude */char longitude[9); /* longitude */Uint32 privacycheck; /* LCS Privacy check */Uint32 Qos; /* requested quality of service */Uint32 priority; /* priority of the request */Char NA-ESRD; /* NA Emergency Services Routing Digits (USA) */Char NA-ESRK; /* NA Emergency Services Routing Key (USA) */} SMSUserLocationThe type variable may take the following values:• 0: not applicable (the user location positioning has not beenperformed).• 1: current position.• 2: current position or last known location;3–5

SMS structures• 3: initial location positioning transmitted in relationship to anemergency call.• 4: defered user location positioning.The geographical shape of the user positioning area is stored in the shapevariable:• 0: not applicable (the user location positioning has not beenperformed).• 1: ellipsoid point with uncertainty circle.• 2: ellipsoid point with uncertainty ellipse.• 3: ellipsoid point with altitude and uncertainty ellipsoid.• 4: ellipsoid arc.• 5: ellipsoid point.NA-ESRD and NA-ESRK parameters are only used in the United States.The privacycheck parameter refers to the requested privacy check actions.Possible requested actions are:• 1: positioning allowed without notifying the user.• 2: positioning allowed with notification to the user.• 3: positioning requires notification and verification by the user,positioning is allowed only if granted by the user or if there is noresponse to the notification.• 4: positioning requires notification and verification by the user,positioning is allowed only if granted by the user.• 5: positioning not allowed3.7 WapDataThe WapData structure store Wap related data, for example those used forWap Push using the SMS_WapPush function.3.8 SMSOperator structureThis structure stores the mobile network operator data.This structure includes:• NCC: Network Country Code (e.g. 208 for France)• MNC: Mobile Network Code (e.g. 001 for Orange in France)• countrycode: ISO 3-letters country code (e.g. FRA for France)3–6

SMS structuresExample 3–7WapData structuretypedef struct{UInt16 destPort;UInt16 srcPort;UInt32 wap_length;UInt32 wap_action;UInt32 wap_encoding;Uint32 wap_options;SMSDateTime created_date;SMSDateTime expiration_date;Char wap_url[100];Char wap_text[50];Char MSISDN[20];Char wap_content[500];} SMSMessageExample 3–8SMSOperator structuretypedef struct{UInt16 NCC;UInt16 MNC;UInt32 status;UInt32 capabilities;UInt32 units;real double price;Char operatorname[20];Char countrycode[3];Char countryprefix[3];Char countryname[20];} SMSOperator• countryprefix: international country dialing prefix (e.g. 33 for France)• units is the number of SMS units needed to send a single SMS to thisdestination.• price is the price invoiced for a single SMS to this destination.3.9 SMSHandset structureThis structure stores the essential data regarding the subscriber mobilehandset.The structure includes:• IMEI: IMEI model• tacid: number asssigned to the terminal TAC .• brand: brand name• model: model name3–7

SMS structuresExample 3–9SMSHandset structuretypedef struct{UInt16 brandnumber;UInt16 modelnumber;UInt32 status;Uint32 capabilities;UInt32 tacid;Char IMEI[15];Char brand[20];Char model[20];} SMSHandsetExample 3–10Structure SmsDateTimeType{typedefUInt32 dateTime;} SMSDateTimeType3.10 SMSDateTimeType structureIt stores date/time used for timestamps and time definitions.3.11 SMS messages types3–8

SMS structuresConstant: Val MeaningSMSMessageTypeReceived 0 Received SMS-MO messageSMSMessageTypeReport 1 SMS notification reportSMSMessageTypeSubmitted 2 Unsolicited Push SMS-MT to betransmitted to the recipientSMSMessageTypeDelivered 3 SMS-MT delivery reportSMSMessageTypeReply 4 SMS-MT message sent in reply to an userrequest performed by SMS-MO.FAXMessageTypeReceived 10 Incoming fax message receivedFAXMessageTypeReport 11 Fax notificationFAXMessageTypeSubmitted 12 Fax message to be transmittedVoiceMessageTypeReport 21 Voice notification reportVoiceMessageTypeSubmitted 22 Voice message to be transmitted usingText To Speech technology3.12 SMS Message content formatConstant: Val MeaningSMSFormatAlphabetic 3 Alphanumeric content in the specified encodingformatSMSFormatNumeric 2 Numeric content (digits from 0 to 9)SMSFormatBinary 4 Binary data (from 00h to FFh)SMSFormatHexa 5 Binary data encoded in hexadecimal (2hexadecimals characters per byte). In this case,msg_length store the number of hexadecimalcharacters, twice the number of effective bytes ofthe messqge content3.13 SMS alphanumeric alphabet encoding constantsThe encoding alphabet (DCS data coding scheme) constants describe theencoding alphabet used for alphanumeric message content.Constant: Val MeaningSMSEncodingIA5 1 CCITT T.50/ISO 8859-1 (default, InternationalReference Alphabet IRA)SMSEncodingGSM 2 GSM 7-bytes default alphabetSMSEncodingUnicode 3 Unicode encoding3–9

SMS structures3.14 Return status and error codesConstant: Val MeaningSMSNormal 1 SuccessSMSError 2 Generic error codeSMSNoVideosms 4 VIDEOSMS is not installed on this sytemSMSInvalidParameter 6 One or several parameters are invalidSMSNoNetwork 8 No available network (TCP/IP or X.25) toaccess the remote SMS gatewaySMSCannotConnect 10 Could not connect to the remote SMSgatewaySMSNoAnswer 12 No answer from remote SMS gatewaywithin alloted timeframeSMSInvalidIPAddress 14 The calling IP address is not authorized toaccess the SMS gateway for the specificaccount or is blacklistedSMSInvalidLoginInfo 16 Invalid company name and/or passwordSMSInvalidMessageId 18 Invalid message number idSMSNoMessage 20 No pending incoming message ornotification for this company or applicationSMSLinkLost 22 TCP/IP or X.25 link to the SMS GatewaylostSMSNoCarrier 24 No available carrier to transmit themessage to the country or operator ofthe recipientSMSMissingParameter 26 Mandatory parameter or field structuremissingSMSNoPrivilege 28 User access rights do not allow to performthe requested operationSMSInvalidUserid 30 Invalid useridSMSCompanyLocked 32 Company account is lockedSMSUserIdLocked 34 User account is lockedSMSAccountNoCredit 36 This prepaid account has not more creditavailabkeSMSObsoleteVersion 38 VideoSMS/Client version is obsolete,please install the mandatory update fromwww.smsfax.com and link again yourapplicationSMSAccountAlreadyExist 40 This account name already existsSMSNotIdentified 42 The user or application has not performeda successful authenticationSMSAccountNotExist 44 This account does not existSMSInvalidDate 46 The specified date is invalid3–10

SMS structuresConstant: Val MeaningSMSFileNotFound 48 The specified file has not been found orcould not been openedSMSUpdateCfgFilees 50 Please update client softwareconfiguration filesSMSMobileAlreadyExist 52 This mobile number is already allocated toanother accountSMSTooManyResendPwd 54 Too many requests to resend the userpasswordSMSExpiredPromoCode 56 The promotional code has expired, thecreation of a new account using this codeis prohibitedSMSVoucherInvalid 58 The specified voucher number is invalidSMSVoucherAlreadySpent 60 The specified voucher number hasalready been spentSMSNotAvailableInCountry 62 The requested function (e.g. accountcreation) is not allowed in the requestercountrySMSOpenPayingAccount 64 A test account could not been opened inthe requester country3.15 SMS messages transmission statusThe error variable of the SMSMessage structure returns the detailedmessage transmission error code that could take the following values:Constant: Val MeaningSMSUnknownSubscriber 51 This mobile number is invalid or unknownSMSCallBarred 53 Call barredSMSMobileUnreacheable 54 The mobile is offline or outside networkcoverage areaSMSOperatorSMSCDown 55 Mobile network operator SMSC is downSMSRedList 56 Target phone number is redlistedSMSBlackList 57 Target phone number is blacklisted (e.g.user has sent STOP request)SMSNumberPorted 58 This mobile number has been ported toanother operatorSMSInternalError 65 Internal ErrorSMSMsgDeletedByOperator 68 Message deleted by an operatorSMSBadlyFormedNumber 70 Invalid number (badly formed)SMSNotInNumberingPlan 71 Invalid number (not in numbering plan)SMSSystemFailure 79 System failure (no more information)SMSHLRSystemFailure 80 HLR system failure3–11

SMS structures3.16 SMPP time formatConstant: Val MeaningSMSVLRSystemFailure 81 VLR system failureSMSTooManyMessages 97 Too many messages for the samerecipientSMSUnknownError 99 Unknown errorSMSDeliveryFail 100 Delivery failed, could not be accepted bymobile (e.g. SIM full)SMSMobileNotEquipped 101 Mobile subscriber handset not equippedto receive SMSSMSNotProvisioned 102 SMS has not been provisionedSMSHandsetError 103 Error in subscriber mobile phoneequipmentSMSCUGReject 104 Closed User Group rejectSMSExpiredMessage 105 The message has expired (validity periodexpired or invalid)Other network-specific errors could also be returned (values greater than120, please refer to the network-specific documentation for each mobilecarrier).The error code is not reset after successful transmission to the recipient,allowing the application to retrieve the reason for a previous transienttransmission error (e.g. mobile offline or outside network coverage).The SMPP time data are encoded in a 16 characters string formatted as"YYMMDDhhmmsstnnp" where• YY: two last digits of the year (99 à 99)• MM: month (01 à 12)• DD: day (01 à 31)• hh: hour (00 à 23)• mm: minutes (00 à 59)• ss: seconds (00 à 59)• t: tenths of seconds (0 à 9)• nn: time difference in quarter of hours between local time andUniversal Time Constant (00 à 48).• p: + or - according local time advance (+) ou late (-) from UTC.3–12

4Networking functions4–1

Networking functionsSMS_ConnectGatewaySMS_ConnectGateway—Connecting to the MCTELVideoSMS gatewayThis function is used to connect to the worldwide MCTEL VideoSMS gatewayFORMAT SMS_ConnectGateway UInt32 **ConnectId, char*GatewayAddress, UInt32l_GatewayAddress, UInt32GatewayPortRETURNSVMS Usage: cond_valuestype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer on pointeraccess: read/writemechanism: by referenceUnique connection identifier, initialized during the connect operation, to bepassed later to all other functions.*GatewayAddressVMS Usage: pointertype: pointer to stringaccess: read onlymechanism: by referencePointer to a character string storing the numeric IP address of theVideoSMS gateway to be called (on OpenVMS, this string must be passedby descriptor).l_GatewayAddressVMS Usage: longwordtype: longwordaccess: read onlymechanism: by referenceuseful length GatewayAddress.GatewayPortVMS Usage: longwordtype: longwordaccess: read onlymechanism: by referenceTCP/IP port number to call.4–2

Networking functionsSMS_ConnectGatewayDESCRIPTIONThis function must be used to connect to the VideoSMS gateway, byspecifying the gateway IP address and port number. It initialize alsothe internal data structures used for SMS communication (it is thereforemandatory to use this function to connect, a direct call to sockets is notsupported).A similar function allowing to connect through X.25 network could besupplied on request.RETURNSTATUSSMSNormalSMSErrorSMSNoVideosmsSMSInvalidParameterSMSNoNetworkSMSCannotConnectSMSAlreadyConnectedSMSNoAnswerSMSInvalidIPAddresssuccessful connection to MCTEL SMS Gateway.an error occured.VideoSMS is not installed on this sytem.one of the specified parameters is invalid.TCP/IP network is down or the system is notconnected to it.the MCTEL SMS Gateway could not be reached fromthe calling network. Check the firewall configuration ifapplicable.the application is already connected to the MCTELSMS Gateway and the customer profile does not allowmultiple simultaneous connections.the MCTEL SMS Gateway has not accepted the callduring the alloted timeframe.the IP address of the calling system is blacklisted oris not authorized to call MCTEL SMS Gateway.EXAMPLES4–3

Networking functionsSMS_LoginGatewaySMS_LoginGateway—Customer authenticationThis function is used for customer authentication on the remote MCTELGateway, after the connection is established.FORMAT SMS_LoginGateway UInt32 *ConnectId,char *companyId, char*password, char *userId, char*userPassword, char *SystemId,UInt32 *LoginOptFlags, UInt32*NbrCreditsRETURNSVMS Usage: cond_valuestype: entier longaccess: lecture seulemechanism: par valeurARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*companyIdVMS Usage: pointertype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the company user identification (onUnix and Windows the string ends by a null character, on OpenVMS thestring is passed by descriptor).*passwordVMS Usage: pointeurtype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the company password (on Unix andWindows the string ends by a null character, on OpenVMS the string ispassed by descriptor).4–4

Networking functionsSMS_LoginGateway*userIdVMS Usage: pointertype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the user identification (username) (onUnix and Windows the string ends by a null character, on OpenVMS thestring is passed by descriptor).*userPasswordVMS Usage: pointeurtype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the user password (on Unix andWindows the string ends by a null character, on OpenVMS the string ispassed by descriptor).*SystemIdVMS Usage: pointertype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the system and application specific(SystemId) of calling system (on Unix and Windows, the string ends by anull character, on OpenVMS the string is passed by descriptor).LoginOptFlagsVMS Usage: longwordtype: SMSLoginOptaccess: read onlymechanism: by valueLongword allowing to specify options. The flag SMSLoginOpt_ReceiveOnlymay be set to specify the application is to connect as a receiver onlyto receive incoming SMS-MO or acknowledgements for SMS-MT eitherpreviously submitted or submitted by another thread.NbrCreditsVMS Usage: pointertype: pointer to longwordaccess: write onlymechanism: by referenceNumber of credits on the user account, if applicable (e.g. prepaid account),otherwise 0.DESCRIPTIONThis function is used to authenticate the user account on the MCTEL SMSGateway. It is necessary to specify the company username and password,and in case of subaccounts the subaccount (user) username and password.The calling application may specify an unique application or account name(systemid) managing the SMS.4–5

Networking functionsSMS_LoginGatewayRETURNSTATUSSMSNormalSMSErrorSMSNoVideosmsSMSLinkLostSMSInvalidParameterSMSNoVideosmsSMSInvalidLoginInfoSMSInvalidUseridSMSCompanyLockedSMSUserIdLockedSMSAccountNoCreditSMSInvalidIPAddressSMSObsoleteVersionsuccessful authentication on MCTEL SMS Gateway.an error occured.VideoSMS is not installed on this sytem.the link to the SMS Gateway has been lost.one of the specified parameters is invalid.VIDÉOSMS n’est pas installé sur ce système.the parameter companyId or password is invalid, theaccess is denied.the parameter userId is invalid.the company account is frozen.the user or application account is frozen.this prepaid account has not available creidt.the calling party IP address is not authorized for thisaccount.the Client API release is obsolete and unsupported,please perform a mandatory update of the ClientAPI and link again the application (latest release ofthe client API may be downloaded free of charge onwww.smsfax.com).EXAMPLES4–6

Networking functionsSMS_LogoutGatewaySMS_LogoutGateway—Logoff from SMS GatewayThis function ends the session to the remote SMS gateway, without breakingthe TCP/IP linK.FORMAT SMS_LogoutGateway UInt32 *ConnectIdRETURNSVMS Usage: cond_valuestype: entier longaccess: lecture seulemechanism: par valeurARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.DESCRIPTIONThis function ends the current session to the remote SMS gateway, withoutbreaking the TCP/IP link. The application may then either disconnect thelink using the SMS_DisconnectGateway or login again using anothercompanyid/userid with the SMS_LoginGateway function.RETURNSTATUSSMSNormalSMSErrorSMSNoVideosmsSMSLinkLostsuccessful logoff from MCTEL SMS Gateway.an error occured.VideoSMS is not installed on this sytem.the link to the SMS Gateway has been lost.EXAMPLES4–7

Networking functionsSMS_EnquireLinkSMS_EnquireLink—Check link state and reset idletimerThis function is used to check the state of the link to the remote SMS gatewayand to reset the idle timer that trigger a timeout and ends the link in case ofinactivity.FORMAT SMS_EnquireLink UInt32 *ConnectIdRETURNSVMS Usage: cond_valuestype: entier longaccess: lecture seulemechanism: par valeurARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.DESCRIPTIONThis function is used to check the state of the link to the remote SMSgateway and to reset the idle timer that trigger a timeout and ends thelink in case of inactivity.By default, after one minute of inactivity, the link between the clientand server is broken by the gateway. To avoid disconnection, if the clientsoftware wish to remain connected without performing SMS operations, itmust issue SMS_EnquireLink commands at regular intervals (less than 1mn).RETURNSTATUSSMSNormalSMSErrorSMSNoVideosmsSMSLinkLostthe link to MCTEL SMS Gateway is still up.an error occured.VideoSMS is not installed on this sytem.the link to the SMS Gateway has been lost.EXAMPLES4–8

Networking functionsSMS_DisconnectGatewaySMS_DisconnectGateway—Disconnect from theremote SMS gatewayThis routine disconnect the TCP/IP link to the MCTEL remote SMS gateway.FORMAT SMS_DisconnectGateway UInt32 *ConnectIdRETURNSVMS Usage: cond_valuestype: entier longaccess: lecture seulemechanism: par valeurARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.DESCRIPTIONThis function disconnect the TCP/IP link from the remote SMS gatewayand release the internal data structures used by VIDEOSMS.The ConnectId pointer is no longer valid after function completion.A similar function (SMS_DisconnectX25Gateway) is supplied when thelink to the SMS Gateway has been established on X.25 network.RETURNSTATUSSMSNormalSMSErrorSMSNoVideosmsSMSLinkLostsuccessful disconnection from MCTEL SMS Gateway.an error occured.VideoSMS is not installed on this sytem.the link to the SMS Gateway has been lost.EXAMPLES4–9

5VIDEOSMS SMS Management Functions (outsidePremium session)5–1

VIDEOSMS SMS Management Functions (outside Premium session)SMS_SendSMS_Send—Send a SMSThis routine is used to send an unsolicited SMS-MT (push-SMS) to a mobilerecipient.FORMAT SMS_Send UInt32 *ConnectId, SMSMessage*Message_to_send, char*private_reference, char *private_dataRETURNSVMS Usage: cond_valuestype: entier longaccess: lecture seulemechanism: par valeurARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*Message_to_sendVMS Usage: pointertype: pointer to SMSMessage structureaccess: read/writemechanism: by referencePointer to a SMSMessage structure type.On input, the following fields of the structure must be initialized:• messagetype: set to SMSMessageTypeSubmitted. According tothe user account privileges, it may be possible to send a fax bysetting to FAXMessageTypeSubmitted) or a voice message thatwill be played using TTS (Text To Speech) technology by settingVoiceMessageTypeSubmitted.• called_number: recipient mobile number (MSISDN), at the followingformat:5 international number, prefixed by a ’+’ and the country code: e.g.:+33612345678.5 international number, prefixed by 00 and the countru code: e.g.:0033612345678• msg_length: useful length of the message to be transmitted.• msg_data: SMS message body, that may content:5 numeric data (msg_format=SMSFormatNumeric.5–2

VIDEOSMS SMS Management Functions (outside Premium session)SMS_Send5 alphanumeric data (default).5 binary data to be transmitted in transparent mode. They could beencoded as binary bytes or as hexadecimal characters.5 a filename storing the data (either alphanumeric or binary) to betransmitted. In this case, the bit 0 of msg_options must be set to1.On output, the msg_reference_number field is filled with the unique SMSmessage identifier assigned by the MCTEL SMS gateway to the message.It is recommended to store this SMS message identifier. When the SMS_ReadStatus is called to check the status of a previously submitted SMS,this message identifier will be required.The following optional data could be specified if needed:• msg_encoding: by default SMSEncodingIA5 (International ReferenceAlphabet ISO 8859-1).• msg_class: spécify the message class:5 0: class 0: flash mode: immediate display of the message on themobile screen without user intervention, but no storage of themessage in the received messages list.5 1: class 1: normal mode (default): the SMS is received and storedin the list of received message. The user must open the receivedmessage list to read the message.5 2: classe 2: stored on SIM card.5 3: classe 3: equipment specific.• msg_format: message encoding format if different than default (defaultis alphabetic SMSFormatAlphabetic)• srcPort: sending port message, only used for binary NBS messages.• destPort: recipient port message, only used for binary NBS messages.• alternate_number: alternate SMS or fax number that could be usedfor message transmission should the primary number be unreacheableand the bit 4 of sms_options be set.• caller_number: sender identifier. In some networks it is possible toset the sender identifier in numeric (phone number) or alphanumericformat. On most networks, the sender identifier could not be setand the SMS is sent using the gateway shortid allocated to the SMSGateway by the network operator.• sender_address: email address of the sender. When bits 20 and/or 21of sms_options are set, a transmission report or error notification couldbe sent by email to this address after either successful transmission orerror.• msg_options: bitarray storing SMS options:5 bit 0 set: the msg_data string does not contain the data to betransmitted but the filename storing the message content.5 bit 1 set: deferred SMS to send at the date/time specified indeferredDate.5–3

VIDEOSMS SMS Management Functions (outside Premium session)SMS_Send5 bit 2 set: SMS to send in priority mode.5 bit 3 set: SMS expiration date specified in expirationDate.5 bit 4: alternate SMS number specified in alternate_number to usewhen the recipient number could not be reached.5 bit 5: SMS acknowledgement request for errors or successfultransmission.5 bit 11: application-specified UDH data stored at the beginningof the msg_data field (before the message content), the UDHuseful length is stored in input in the sms_error field. The sendingapplication is responsible for the UDH generation and correctsyntax.5 bit 16 set: allows routing of incoming SMS replies to the originator.5 bit 17 set: the application_name field is used to store applicationspecificdata (maximum length = 50 bytes).5 bit 18 set: the private_reference field encodes the applicationprivate reference that will be returned in the message transmissionacknowledgements.5 bit 19 set: EMS message specification (e.g. iMelody).5 bit 20 set: request that an error notification be transmitted byemail to the sender in case of transmission error.5 bit 21 set: request for a transmission acknowledgement to be sendby email after SMS successful transmission.5 bit 24 set: in case of transmission error, the SMS must not beremoved from the send queue, but will stay in the queue waitingfor a supervisor action.5 bit 26 set: SMS to be processed in "replace" mode, i.e. replacingany previously submitted and still not transmitted SMS for thesame recipient.5 bit 29 mis: request of HTTP/HTML notification on SMS successfulltransmission or error to the URL specified in the account profile.5 bit 30 set: message to be approved by a supervisor, will be held inthe send queue until validation.*private_refVMS Usage: pointertype: pointer to a string (15 characters maximum)access: read onlymechanism: by referencePointer to a 15 characters string storing the application message privateidentifier. Only used when the bit 18 of msg_options is set.*private_dataVMS Usage: pointertype: pointer to a string (50 characters maximum)access: read onlymechanism: by reference5–4

VIDEOSMS SMS Management Functions (outside Premium session)SMS_SendPointer to a 50 characters maximum string storing application specificdata, to be returned with notifications. Only used when the bit 17 of msg_options is set.DESCRIPTIONThis function is used to send a SMS.The SMS content may be transmitted to the function or stored in a filewhose filename is passed to the function. In this last case, the file must bea sequential file.The SMS may be send in normal mode, in priority mode, or in deferredmode at a specified date/time. It is also possible to specify an expirationdate for the SMS in order to have it discarded if not transmitted.RETURNSTATUSSMSNormalSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSFileEmptySMSFileNotFoundSMSTooLongSMSNoCarrierSMSUnauthorizedCarrierSMSInvalidAddressSMSUnrecognizedAddressSMSInvalidDateSMS transmission request received by the MCTELGateway. This status does not mean that the SMShas been successfully transmitted and received bythe recipient but that it has been received by the SMSGateway and queued for transmission.The msg_reference_number variable returns the SMSentry number in the SMS Gateway. This number isunique amongst all the SMS managed by the SMSGateway and should be used to request the SMSstatus.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.the specified file is empty, the SMS will not betransmitted.the specified file has not been found, the SMS will notbe transmitted.the specified message size exceed the maximum sizeallowed by the network.the SMS could not be transmitted to the intendedrecipient because the MCTEL SMS Gateway is notconnected to the mobile network operator, or the linkto the mobile network is down and no alternate routecould be selected during the alloted timeframe.the sender account is not allowed to send SMS to theintended mobile operator.the specified recipient mobile number is invalid orunassigned.the SMS gateway could not recognize the recipientdestination network, please check the recipientnumber syntax and validity.a specified date/time is invalid.5–5

VIDEOSMS SMS Management Functions (outside Premium session)SMS_SendSMSThrottleErrorSMSAccountNoCreditthe sender application or account has exceededthe maximum number of SMS submitted alloted bytimeframe.Not enought credits available on this prepaid accountto send the SMSEXAMPLES5–6

VIDEOSMS SMS Management Functions (outside Premium session)SMS_WAPPushSMS_WAPPushThis function sends a Push Wap SMS to the intended recipient.FORMAT SMS_WAPPush UInt32 *ConnectId, SMSMessage*SMSMessage, WapData *WapData,char *private_reference, char*private_dataRETURNSVMS Usage: cond_valuestype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*Message_to_sendVMS Usage: pointertype: pointer to SMSMessage structureaccess: read/writemechanism: by referencePointer to a SMSMessage structure type.On input, the following fields of the structure must be initialized:• messagetype: set to SMSMessageTypeSubmitted.• called_number: recipient mobile number (MSISDN), at the followingformat:5 international number, prefixed by a ’+’ and the country code: e.g.:+33612345678.5 international number, prefixed by 00 and the countru code: e.g.:0033612345678On output, the msg_reference_number field is filled with the unique SMSmessage identifier assigned by the MCTEL SMS gateway to the message.It is recommended to store this SMS message identifier. When the SMS_ReadStatus is called to check the status of a previously submitted SMS,this message identifier will be required.5–7

VIDEOSMS SMS Management Functions (outside Premium session)SMS_WAPPushThe following optional data could be specified if needed:• msg_class: spécify the message class:5 0: class 0: flash mode: immediate display of the message on themobile screen without user intervention, but no storage of themessage in the received messages list.5 1: class 1: normal mode (default): the SMS is received and storedin the list of received message. The user must open the receivedmessage list to read the message.5 2: classe 2: stored on SIM card.5 3: classe 3: equipment specific.• srcPort: sending port message, only used for binary NBS messages.• destPort: recipient port message, only used for binary NBS messages.• alternate_number: alternate SMS or fax number that could be usedfor message transmission should the primary number be unreacheableand the bit 4 of sms_options be set.• caller_number: sender identifier. In some networks it is possible toset the sender identifier in numeric (phone number) or alphanumericformat. On most networks, the sender identifier could not be setand the SMS is sent using the gateway shortid allocated to the SMSGateway by the network operator.• sender_address: email address of the sender. When bits 20 and/or 21of sms_options are set, a transmission report or error notification couldbe sent by email to this address after either successful transmission orerror.• msg_options: bitarray storing SMS options:5 bit 1 set: deferred SMS to send at the date/time specified indeferredDate.5 bit 2 set: SMS to send in priority mode.5 bit 3 set: SMS expiration date specified in expirationDate.5 bit 4: alternate SMS number specified in alternate_number to usewhen the recipient number could not be reached.5 bit 5: SMS acknowledgement request for errors or successfultransmission.5 bit 16 set: allows routing of incoming SMS replies to the originator.5 bit 17 set: the application_name field is used to store applicationspecificdata (maximum length = 50 bytes).5 bit 18 set: the private_reference field encodes the applicationprivate reference that will be returned in the message transmissionacknowledgements.5 bit 20 set: request that an error notification be transmitted byemail to the sender in case of transmission error.5 bit 21 set: request for a transmission acknowledgement to be sendby email after Wap Push successful transmission.5–8

VIDEOSMS SMS Management Functions (outside Premium session)SMS_WAPPush5 bit 24 set: in case of transmission error, the Wap Push SMS mustnot be removed from the send queue, but will stay in the queuewaiting for a supervisor action.5 bit 30 set: message to be approved by a supervisor, will be held inthe send queue until validation.*WapDataVMS Usage: pointertype: pointer to a WapData type structureaccess: read/writemechanism: by referencePointer to a WapData structure type. The following fields must beinitialized:• wap_url: Wap URL to Push (except when the URL is to be generateddynamically).Optionally, it is possible to specify:• wap_content: multimedia content to be transmitted to the recipient,either passed directly or by its filename.• wap_text: URL text description to be transmitted to the recipientalong the URL.• wap_action: Wap push action that may be:5 medium (defaut): unobstrusive display when possible.5 high: immediate display even if obstrusive (to be avoided ifpossible).5 low: display when possible.5 none5 delete• wap_options: various options could be selected by setting theappropriate bits of this longword.5 bit 0 set: the wap_content field does not contain the multimediacontent to push, but the filename storing this content.5 bit 1 set: the Wap URL must be generated dynamically in order togive access to the multimedia content passed in wap_content.5 bit 2 set: the Wap URL dynamically generated must be singleuse only: after a single downloading by the user, the multimediacontent will no longer be reacheable through this URL.5 bit 3 set: URL creation date must be set to wap_creation_time.5 bit 4 set: URL expiration date must be set to wap_expiration_time.*private_refVMS Usage: pointertype: pointer to a string (15 characters maximum)access: read only5–9

VIDEOSMS SMS Management Functions (outside Premium session)SMS_WAPPushmechanism: by referencePointer to a 15 characters string storing the application message privateidentifier. Only used when the bit 18 of msg_options is set.*private_dataVMS Usage: pointertype: pointer to a string (15 characters maximum)access: read onlymechanism: by referencePointer to a 50 characters maximum string storing application specificdata, to be returned with notifications. Only used when the bit 17 of msg_options is set.DESCRIPTIONThis routine could be used to send via a Wap Push SMS multimediacontent to the mobile user, for example:• Wap page encoded in WML format.• polyphonic ringtone.• color picture.• JM2E Java application.• 3gpp video file.• and so on.The only requirement is for the recipient to have a Wap compatible phoneand to have Wap or GPRS subscription enabled in order to be able toautomatically download the multimedia content.The content referred by the Wap Push URL may be:• stored in advance on the Wap server, in this case the Wap URL mustbe passed to the function in the Wap_URL field.• transmitted by the function to the server. In this case, it will be storedin the file specified by the URL passed in Wap_URL field. It is alsopossible not to specify the URL by to let the server to dynamicallystore the content and generate its own URL, by setting the bit 1 ofwap-options. This URL may be single use only if the bit 2 of wap_options is set.The Wap Push may be send in normal mode, in priority mode, or indeferred mode at a specified date/time. It is also possible to specify anexpiration date for the Wap Push in order to have it discarded if nottransmitted. An expiration date may also be set for the URL in order tospecify the URL is no longer valid after this date (some phones may havedifficulty to process Wap Push URL with creation date or expiration dateset, so be careful using this function and use it only if really required byyour application needs).5–10

VIDEOSMS SMS Management Functions (outside Premium session)SMS_WAPPushRETURNSTATUSSMSNormalSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSFileEmptySMSFileNotFoundSMSTooLongSMSNoCarrierSMSUnauthorizedCarrierSMSInvalidAddressSMSUnrecognizedAddressSMSInvalidDateSMSThrottleErrorSMSAccountNoCreditSMS transmission request received by the MCTELGateway. This status does not mean that the SMShas been successfully transmitted and received bythe recipient but that it has been received by the SMSGateway and queued for transmission.The msg_reference_number variable returns the SMSentry number in the SMS Gateway. This number isunique amongst all the SMS managed by the SMSGateway and should be used to request the SMSstatus.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.the specified file is empty, the SMS will not betransmitted.the specified file has not been found, the SMS will notbe transmitted.the specified message size exceed the maximum sizeallowed by the network.the SMS could not be transmitted to the intendedrecipient because the MCTEL SMS Gateway is notconnected to the mobile network operator, or the linkto the mobile network is down and no alternate routecould be selected during the alloted timeframe.the sender account is not allowed to send SMS to theintended mobile operator.the specified recipient mobile number is invalid orunassigned.the SMS gateway could not recognize the recipientdestination network, please check the recipientnumber syntax and validity.a specified date/time is invalid.the sender application or account has exceededthe maximum number of SMS submitted alloted bytimeframe.Not enought credits available on this prepaid accountto send the SMSEXAMPLES5–11

VIDEOSMS SMS Management Functions (outside Premium session)SMS_ReadStatusSMS_ReadStatus—Get SMS statusThis function returns the detailed state of a SMS submitted for transmission.FORMAT SMS_ReadStatus UInt32 *ConnectId,*Message_to_query, char*PrivateReference, char*PrivateDataRETURNSVMS Usage: cond_valuestype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*Message_to_queryVMS Usage: pointertype: pointer to a SMSMessage type structureaccess: read/writemechanism: by referencePointer to a SMSMessage structure type.*PrivateReferenceVMS Usage: pointertype: pointer to a 15-characters stringaccess: write onlymechanism: by referencePointer to a 15-characters string receiving the application message privateidentifier. Only returned when the bit 18 of msg_options is set.*PrivateDataVMS Usage: pointertype: pointer to a 50-characters stringaccess: read onlymechanism: by referencePointer to a 50 characters maximum string receiving application specificdata. Only returned when the bit 17 of msg_options is set.5–12

VIDEOSMS SMS Management Functions (outside Premium session)SMS_ReadStatusDESCRIPTIONThis function returns the detailed state of a SMS submitted fortransmission.On input the msg_reference_number structure field must be initializedby the unique SMS reference number returned by the SMS_Send, SMS_WapPush or SMS_Reply function.The function queries the SMS gateway and update the following fields ofthe SMSMessage structure:• sms_state: SMS state, that may take the following values:5 1: DELIVERED: SMS successfully transmitted (a receptionacknowledgement has been received).5 2: UNDELIVERABLE: fatal error, SMS untransmitted and deletedfrom send queue. The error_cause variable will return the errorcause.5 3: TRANSMITTED: SMS considered as transmitted to theintended recipient (this status is returned when the messagehas been successfully transmitted to the network operator gatewayand acknowledged by this gateway, but when either no useracknowledgement has been requested or when the recipientnetwork could not transmit user acknowledgements notifications).5 10: pending state waiting for supervisor approval.5 11: due to several errors, the SMS could not be transmitted andwill stay in send queue waiting for user or supervisor action. Theerror_cause variable will return the last known error cause.5 12: EN ROUTE: in transmission process by the recipient operatornetwork.5 13: ERROR: an error occured during the SMS transmission, thetransmission will be automatically retried later. The error_causevariable will return the last known error cause.5 18: SCHEDULED: in the send queue, will be transmitted as soonas possible.5 19: PRIORITY: priority SMS, will be transmitted as soon aspossible and before other non-priority SMS.5 21: waiting for scheduled delayed date/time.5 99: invalid or unknown status.• error_cause: detailed error cause, may take the following values:5 50: generic error.5 51: specified mobile number does not exist.5 52: this mobile is unreacheable.5 53: calls to this mobile are prohibited (call barred).5 54: mobile is offline or outside network coverage.5 55: network operator SMS-Center offline or unreacheable.5–13

VIDEOSMS SMS Management Functions (outside Premium session)SMS_ReadStatus5 56: red list number.5 57: black list number.5 58: number ported by another operator (or in some cases invalidnumber).5 64: host error.5 65: internal error.5 66: message expiration date reached.5 67: prohibited operation.5 68: message deleted by a supervisor.5 99: other error.5 other network-specific error codes > 100 may also be returned,please refer to the manual regarding the network you are using.• price: SMS send price, in the gateway default currency.RETURNSTATUSSMSNormalSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSInvalidMessageIdSMSNoPrivilegethe SMS has been retrieved, the structure is updatedwith current SMS status.a generic error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.the message id field specified does not match a validmessage identifier.the message id specified in the request is valid butbelong to another user and/or company, accessdenied.5–14

VIDEOSMS SMS Management Functions (outside Premium session)SMS_GetMessageSMS_GetMessage—SMS-MO or transmissionacknowledgement receptionThis function is used to get either incoming SMS-MO or transmissionacknowledgements in real time.FORMAT SMS_GetMessage UInt32 *ConnectId, SMSMessage*Message_receivedRETURNSVMS Usage: cond_valuestype: entier longaccess: lecture seulemechanism: par valeurARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*Message_receivedVMS Usage: pointertype: pointer to SMSMessage structureaccess: writemechanism: by referencePointer to a SMSMessage structure type.DESCRIPTIONThis routing allows the application to receive on real time incoming SMS-MO and transmission acknowledgements for SMS-MT either previouslysent or sent by a separate thread.If no SMS-MO or transmission acknowledgement is pending for thisaccount, the function will wait and will only return the control to thecalling program when one is received or the link is lost. The SMS_GetMessage will take charge of maintaining the link by transmitting SMS_EnquireLink at regular intervals (to avoid to get disconnected on timeoutby the SMS Gateway).The calling application will have to look at the message_type field ofthe SMSMessage structure to know if it is an incoming SMS-MO or atransmission acknowledgement regarding a previously submitted SMS-MT.5–15

VIDEOSMS SMS Management Functions (outside Premium session)SMS_GetMessageRETURNSTATUSSMSNormalSMSErrorSMSLinkLostSMSNoVideosmsSMSNotConnectedSMSNotAuthentifiedSMSInvalidParametera SMS-MO or a notification acknowledgement hasbeen received, the structure returns the relevant data.a generic error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.the system is not connected to VIDEOSMS Gateway.the system is not authentified on the remoteVIDEOSMS Gateway.one of the specified parameter is invalid.EXAMPLES5–16

6Other Network Functions6–1

Other Network FunctionsSMS_GetLocationSMS_GetLocation—Location positioning requestThis function request the geographical location positioning of a given mobileuser.FORMAT SMS_GetLocation UInt32 *ConnectId, *UserLocationRETURNSVMS Usage: cond_valuestype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.MobileMSISDNVMS Usage: pointertype: pointer to stringaccess: read onlymechanism: by referenceMobile MSISDN to locate in international format.*UserLocationVMS Usage: pointertype: pointer to a SMSUserLocation structure typeaccess: write onlymechanism: by referencePointer to a SMSUserLocation type structure.DESCRIPTIONThis function query the mobile network operator to request the currentor last known user geographical location. It is possible the specify themobile MSISDN, if not specified the request will apply to the currentlyopen Premium SMS session.This function returns the success or failure status and in case of successwill return the geographical location positioning in the UserLocationstructure. The last known date of this structure must be checked toensure the accuracy of the returned location.The request may fail if the user or the network does not allow the locationpositioning operation of if the SMS Gateway is not allowed to perform thisrequest.6–2

Other Network FunctionsSMS_GetLocationRETURNSTATUSSMSNormalSMSNoLocationSMSNoPrivilegeSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSNoCarrierSMSUnauthorizedCarrierSMSRoamingNotAllowedSMSInvalidAddressSMSUnrecognizedAddressSMSAccountNoCreditsuccessful location positioning, user location isreturned in the UserLocation structure.correct function operation, but the location couldnot be returned by the network operator SMS-Center for various reasons (amongst the possibleSS7/MAP error status): Insufficient resources,Insufficient Measurement Data, Location procedurenot completed, Quality of Service not attainable,position method not available in network, positionmethod not available in location area.access rights of the user account does not allow toperform user location positioning requests.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.the user could not be located because the MCTELSMS Gateway is not connected to the mobile networkoperator, or the link to the mobile network is downand no alternate route could be selected during thealloted timeframe.the sender account is not allowed to access the usermobile operator.the user mobile network could not be accessed inroaming mode by the gateway available networks.the user mobile number is invalid or unassigned.the SMS gateway could not recognize the recipientdestination network, please check the recipientnumber syntax and validity.Not enought credits available on this prepaid accountto perform the location requestEXAMPLES6–3

Other Network FunctionsSMS_FindOperatorSMS_FindOperator—Retrieve mobile networkoperatorThis function request the mobile network operator managing the givensubscriber.FORMAT SMS_FindOperator UInt32 *ConnectId, string*MobileMSISDN, SMSOperator*Operator, UInt32 *OptFlagsRETURNSVMS Usage: cond_valuestype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.MobileMSISDNVMS Usage: pointertype: pointer to stringaccess: read onlymechanism: by referenceMobile MSISDN whose operator is to be retrieved in international format.*OperatorVMS Usage: pointertype: pointer to a SMSOperator structure typeaccess: write onlymechanism: by referencePointer to a SMSOperator type structure.OptFlagsVMS Usage: longtype: longwordaccess: read onlymechanism: by valueLongword allowing to specify the retrieval mode. The flag SMSOperator_SS7 may be set to request a retrieval over the SS7 network.6–4

Other Network FunctionsSMS_FindOperatorDESCRIPTIONThis function returns the mobile network operator managing the specifiedsubscriber.According to the value of OptFlags, the function may return the mobilenetwork operator to which the MSISDN was initially assigned usingthe official country numbering plan, or perform over the SS7 signallingnetwork a request in real time to retrieve the current mobile networkoperator, taking in account ported numbers.This function will also return the operator and country name and code, aswell the main network characteristics and the cost of sending a SMS tothis network.RETURNSTATUSSMSNormalSMSNoPrivilegeSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSNoCarrierSMSUnauthorizedCarrierSMSRoamingNotAllowedSMSInvalidAddressSMSUnrecognizedAddressSMSAccountNoCreditsuccessful operator retrieval, operator is returned inthe SMSOperator structure.access rights of the user account does not allow toperform operator retrieval requests.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.the user could not be located because the MCTELSMS Gateway is not connected to the mobile networkoperator, or the link to the mobile network is downand no alternate route could be selected during thealloted timeframe.the sender account is not allowed to access the usermobile operator.the user mobile network could not be accessed inroaming mode by the gateway available networks.the user mobile number is invalid or unassigned.the SMS gateway could not recognize the recipientdestination network, please check the recipientnumber syntax and validity.Not enought credits available on this prepaid accountto perform the requestEXAMPLES6–5

Other Network FunctionsSMS_FindHandsetInfoSMS_FindHandsetInfo—Retrieve handset type andcharacteristicsThis function request the handset type of the mobile subscriber.FORMAT SMS_FindHandsetInfo UInt32 *ConnectId,string *MobileMSISDN,SMSHandset *Handset,UInt32 *OptFlagsRETURNSVMS Usage: cond_valuestype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.MobileMSISDNVMS Usage: pointertype: pointer to stringaccess: read onlymechanism: by referenceMobile MSISDN whose handset is to be retrieved in international format.*HandsetVMS Usage: pointertype: pointer to a SMSHandset structure typeaccess: write onlymechanism: by referencePointer to a SMSHandset type structure.OptFlagsVMS Usage: longtype: longwordaccess: read onlymechanism: by valueLongword allowing to specify the retrieval mode. The flag SMSOperator_SS7 may be set to request a retrieval over the SS7 network instead ofmaking a search on internal MCTEL databases.6–6

Other Network FunctionsSMS_FindHandsetInfoDESCRIPTIONThis function returns the mobile handset used by the specified subscriber.According to the value of OptFlags, the function may return the handsetinformation stored in the MCTEL databases (and either supplied bythe operator Premium Gateway or retrieved from a previous search) orperform over the SS7 signalling network a request in real time to retrievethe current mobile IMEI.This function may also return the main handset characteristics.RETURNSTATUSSMSNormalSMSNoPrivilegeSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSNoCarrierSMSUnauthorizedCarrierSMSRoamingNotAllowedSMSInvalidAddressSMSUnrecognizedAddressSMSAccountNoCreditsuccessful handset information retrieval, operator isreturned in the SMSHandset structure.access rights of the user account does not allow toperform handset information retrieval requests.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.the user could not be located because the MCTELSMS Gateway is not connected to the mobile networkoperator, or the link to the mobile network is downand no alternate route could be selected during thealloted timeframe.the sender account is not allowed to access the usermobile operator.the user mobile network could not be accessed inroaming mode by the gateway available networks.the user mobile number is invalid or unassigned.the SMS gateway could not recognize the recipientdestination network, please check the recipientnumber syntax and validity.Not enought credits available on this prepaid accountto perform the requestEXAMPLES6–7

7Premium SMS Session Management Functions7–1

Premium SMS Session Management FunctionsSMS_ReadSMS_Read—Read incoming SMS receivedThis function is used to read an incoming SMS-MO received by the gatewayand destined to the application.FORMAT SMS_Read UInt32 *ConnectId, *Message_receivedRETURNSVMS Usage: cond_valuestype: entier longaccess: lecture seulemechanism: par valeurARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*Message_receivedVMS Usage: pointertype: pointer to a SMSMessage type structureaccess: write onlymechanism: by referencePointer to a SMSMessage type structure.DESCRIPTIONThis function is used by the application to get a SMS-MO request sentfrom a remote mobile user to this application.This function must be called first to initialize the session context.If no message has been received for this application, the SMSNoMessage isreturned. This application must then either disconnect and connect againlater, or issue another SMS_Read request at regular intervals.RETURNSTATUSSMSNormalSMSNoMessageSMSNotConnectedSMSNotAuthentifieda SMS-MO message for this application has beenreceived by the gateway and is returned in theMessage_received structure.no received message for this application.the system is not connected to the SMS Gateway.the application is not authentified on the SMSgateway.7–2

Premium SMS Session Management FunctionsSMS_ReadSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameteran unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.EXAMPLES7–3

Premium SMS Session Management FunctionsSMS_GetSessionInfoSMS_GetSessionInfo—Get session informationcontextThis function gets the session information context.FORMAT SMS_GetSessionData UInt32 *ConnectId, *SessionRETURNSVMS Usage: cond_valuestype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*SessionVMS Usage: pointertype: pointer to SMSSession structureaccess: write onlymechanism: by referencePointer to a SMSSession type structure.DESCRIPTIONThis function returns the main informations of the session, including:• the unique user session number. A single Premium SMS session mayinclude several requests processed sequentially (couples of SMS-MOrequests/SMS-MT answers).• the calling user phone number. In some countries and network, theuser mobile MSISDN is obfuscated and replaced by an alias by thenetwork operator to prohibit the SMS Premium information providerto store the phone numbers in a database for commercial or marketingpurposes.• Premium SMS number called by user.• data request (SMS-MO content), encoded to ISO 8858-1 alphabet bydefault except if another alphabet is specified.• request sequence number, beginning to 1 for the first SMS-MO requestand incremented by 1 for each new SMS-MO received from the user.7–4

Premium SMS Session Management FunctionsSMS_GetSessionInfoRETURNSTATUSSMSNormalSMSErrorSMSNoSessionSMSNoVideosmsSMSInvalidParameterthe session structure data are returned in theSMSSession structure.a generic error occured.there is no active session.VIDEOSMS is not installed on this system.one of the specified parameters is invalid.EXAMPLES7–5

Premium SMS Session Management FunctionsSMS_GetSessionDataSMS_GetSessionData—Reading application-specificsession dataThis function returns application-specific data previously saved for thisPremium SMS session.FORMAT SMS_GetSessionData UInt32 *ConnectId, char*data_name, data_type,data_length, *data_valueRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*data_nameVMS Usage: stringtype: pointer to stringaccess: read onlymechanism: by referenceVariable name to get. If this string is empty, VIDEOSMS will returneach saved variables one after the other at each function call and thenSMSNoMoreData when all variable will have been returned.data_typeVMS Usage: longwordtype: longwordaccess: read/writemechanism: by reference.legal values:• 1: Int (longword).• 2: Int (word).• 3: character string• 4: application-specific data structure7–6

Premium SMS Session Management FunctionsSMS_GetSessionDatadata_lengthVMS Usage: longwordtype: longwordaccess: read/writemechanism: par référenceOn input, maximum buffer size of the buffer (for character string orapplication-specific data structure, or 0 if unspecified. On output, usefullength of the data returned in data_content*data_valueVMS Usage: variabletype: pointer on a buffer of large enough sizeaccess: write onlymechanism: by referencevalue of the returned variable. In the case of an application-specific datastructure, it is the application responsibility to pass a pointer to the correctstructure.DESCRIPTIONRETURNSTATUSSMSNormalSMSErrorSMSNoSessionSMSNoVideosmsSMSInvalidParameterthe variable has been found, the value is returned indata_value.an error occured.there is no active session.VIDÉOSMS is not installed on this system.one of the specified parameter is invalid.EXAMPLESExample7–7

Premium SMS Session Management FunctionsSMS_UpdateSessionDataSMS_UpdateSessionData—Savingapplication-contextspecific dataThis function is used to save application-specific data for this Premium SMSsession, to be returned later during a next user SMS exchange for the samesession by the SMSGetSessionData call.FORMAT SMS_UpdateSessionData UInt32 *ConnectId, char*data_name, data_type,data_length, *data_valueRETURNSVMS Usage: cond_valuetype: entier longaccess: lecture seulemechanism: par valeurARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*data_nameVMS Usage: stringtype: pointeur sur chaîne de caractèresaccess: lecturemechanism: par référenceNom de la variable spécifique à sauvegarder.data_typeVMS Usage: longwordtype: entier longaccess: lecture seulemechanism: par référencetype des données à sauvegarder.legal values:• 1: Int (longword).• 2: Int (word).• 3: character string• 4: application-specific data structure7–8

Premium SMS Session Management FunctionsSMS_UpdateSessionData• 5: real double precision• 99: request to delete the saved variable from the session context. Inthis case, the parameters data_length and data_value are ignored.data_lengthVMS Usage: longwordtype: longwordaccess: read onlymechanism: by referenceuseful lenght to data to record, stored in data_content*data_valueVMS Usage: variabletype: pointer to a bufferaccess: read onlymechanism: by referencedata to be stored.DESCRIPTIONThis function is used to save application-specific data for this PremiumSMS session, to be returned later during a next user SMS exchange forthe same session by the SMSGetSessionData call.The data will be effectively saved on the SMS gateway during the sendreply message using a SMS_Reply call.RETURNSTATUSSMSNormal application-specific data successfully recorded .SMSNoSessionthere is no active session.SMSBufferSizeExceeded data buffer size exceeds available data storage spacefor this session.SMSErroran error occured.SMSNoVideosmsVIDÉOSMS is not installed on this system.SMSInvalidParameter one of the specified parameter is invalid.EXAMPLESExemple7–9

Premium SMS Session Management FunctionsSMS_ReplySMS_Reply—Send back SMS-MT in reply to theSMS-MO requestThis function is used to send a SMS-MT in reply to the SMS-MO receivedduring the Premium SMS session. endoverview>FORMAT SMS_Reply UInt32 *ConnectId, *Message_to_send,SMSSessionClosedRETURNSVMS Usage: cond_valuestype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*Message_to_sendVMS Usage: pointertype: pointer to a SMSMessage type structureaccess: read/writemechanism: by referencePointer to a SMSMessage type structure.On input, the following structure fields must be initialized:• messagetype: set to SMSMessageTypeReply.• msg_length: useful length of message to be transmitted.• msg_data: SMS message content that may contain:5 numeric data only (msg_format=SMSFormatNumeric.5 alphanumeric data only (default).5 binary data either encoded in binary format or hexadecimal format.5 a filename storing the data to be transmitted (in this case the msg_options bit 0 must be set).On output, the msg_reference_number field returns the unique SMS messageidentifier assigned by the SMS est rempli avec l’identifiant unique assigné parla passerelle au message SMS.7–10

Premium SMS Session Management FunctionsSMS_ReplyThe following optional data could be specified if needed:• msg_encoding: by default SMSEncodingIA5 (International ReferenceAlphabet ISO 8859-1).• msg_class: spécify the message class:5 0: class 0: flash mode: immediate display of the message onthe mobile screen without user intervention, but no storage of themessage in the received messages list.5 1: class 1: normal mode (default): the SMS is received and storedin the list of received message. The user must open the receivedmessage list to read the message.5 2: classe 2: stored on SIM card.5 3: classe 3: equipment specific.• msg_format: message encoding format if different than default (default isalphabetic SMSFormatAlphabetic)• srcPort: sending port message, only used for binary NBS messages.• destPort: recipient port message, only used for binary NBS messages.• sender_address: email address of the sender. When bits 20 and/or 21 ofsms_options are set, a transmission report or error notification could besent by email to this address after either successful transmission or error.• sms_action: SMS-Center action (only to be used for some networks):5 0: (SMS_NOOP) no operation, uncharged message (default).5 1: (SMS_END) transactional session close (payment requested) andservice session close, same as SMS_CONFIRM + SMS_CLOSE.5 2 (SMS_CONFIRM) transactional session close (payment requested).5 3 (SMS_CLOSE) service session close.• msg_options: bitarray storing SMS options:5 bit 0 set: the msg_data string does not contain the data to betransmitted but the filename storing the message content.5 bit 3 set: SMS expiration date specified in expirationDate.5 bit 5: SMS acknowledgement request for errors or successfultransmission.5 bit 11: application-specified UDH data stored at the beginning of themsg_data field (before the message content), the UDH useful lengthis stored in input in the sms_error field. The sending application isresponsible for the UDH generation and correct syntax.5 bit 20 set: request that an error notification be transmitted by email tothe sender in case of transmission error.5 bit 21 set: request for a transmission acknowledgement to be send byemail after SMS successful transmission.7–11

Premium SMS Session Management FunctionsSMS_ReplySMSSessionClosedVMS Usage: longwordtype: longwordaccess: read onlymechanism: by referenceFlag set to 1 if the current transactional session must be closed, that is if nofurther exchange is expected for this session.DESCRIPTIONThis function sends back a SMS-MT response message answering apreviously received SMS-MO request from the remote user.The content of the SMS to be transmitted may be passed to the functionor stored in a sequential text or binary file whose filename is passed to thefunction.There is no need to specify the recipient mobile number as the user mobilenumber is known.On some networks, the mobile operator SMS-Center manages a primitivesession context, including a transactional session (one for each payingexchange) and a service session (alloted to a given mobile user). Onthose networks, the sms_action variable is used to manage the SMS-Centersession:• the CONFIRM action closes the transactional session and triggers theuser charging if applicable.• the CLOSE action closes the service session.• the END action closes both sessions (transactional and service).• the VIDEOSMS internal session and its context (several relatedexchanges) may also be closed by setting the sms_sessionclosed flag.RETURNSTATUSSMSNormalSMSErrorSMSLinkLostSMSNoSessionSMS transmission request received by the MCTELGateway. This status does not mean that the SMShas been successfully transmitted and received bythe recipient but that it has been received by the SMSGateway and queued for transmission.The msg_reference_number variable returns the SMSentry number in the SMS Gateway. This number isunique amongst all the SMS managed by the SMSGateway and should be used to request the SMSstatus.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.there is no currently open session, there is no way toanswer as no remote user is known, the SMS_Sendmust be used to send a SMS by specifying the mobileuser MSISDN.7–12

Premium SMS Session Management FunctionsSMS_ReplySMSNoVideosmsSMSInvalidParameterSMSMissingParameterSMSFileEmptySMSFileNotFoundSMSTooLongVIDEOSMS is not installed on this system.one of the specified parameter is invalid.one of the mandatory parameters of the Message_to_send structure is not filled in.the specified file is empty, the SMS will not betransmitted.the specified file has not been found, the SMS will notbe transmitted.the specified message size exceed the maximum sizeallowed by the network.EXAMPLES7–13

8Management functions8–1

Management functionsSMS_CreateAccountSMS_CreateAccount—Opening a new user accountThis function is used to create a new user accountFORMAT SMS_CreateAccount UInt32 *ConnectId, structure*UserAccountStructure,char *URLtodisplay, char*ProposedUsernameRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*userAccountStructureVMS Usage: pointertype: pointer to structureaccess: read onlymechanism: by referencePointer to a UserAccountStructure type structure storing the user accountcharacteristics.*URLtodisplayVMS Usage: stringtype: pointer to stringaccess: write onlymechanism: by referencePointer to a character string storing a Web URL that could be displayed touser after the operation.*ProposedUsernameVMS Usage: stringtype: pointer to stringaccess: write onlymechanism: by referencePointer to a character string storing an available username that could beproposed to the user as new username should the operation fails because thespecified username already exist.8–2

Management functionsSMS_CreateAccountDESCRIPTIONThis function is used to create a new user account.It could return the URL of a Web page to be displayed to the user aftersuccessful account creation or failure.Should the account creation fails because the proposed username alreadyexists, the function may return in *ProposedUsername an available usernamethat could be used to retry the account creation operation.RETURNVALUESSMSNormalSMSNoPrivilegeSMSAccountAlreadyExistSMSMobileAlreadyExistSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSMissingParameterthe new user account has been created.the access rights of the caller account do not allowaccount creation operation.this account already exists, please select another one.this mobile number is already alloted to anotheraccount.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.one of the mandatory parameters of theUserAccountStructure is not filled in.EXAMPLESExample8–3

Management functionsSMS_GetAccountInfoSMS_GetAccountInfo—Read user accountinformationThis function returns user account detailed information.FORMAT SMS_GetAccountInfo UInt32 *ConnectId,char *companyId, char*password, char *userId, char*userpassword, structure*userAccountStructureRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*companyIdVMS Usage: pointertype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the company user identification (on Unixand Windows the string ends by a null character, on OpenVMS the string ispassed by descriptor).*passwordVMS Usage: pointeurtype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the company password (on Unix andWindows the string ends by a null character, on OpenVMS the string ispassed by descriptor).*userIdVMS Usage: pointertype: pointer to character stringaccess: read only8–4

Management functionsSMS_GetAccountInfomechanism: by referencePointer to a character string storing the user identification (username) (on Unixand Windows the string ends by a null character, on OpenVMS the string ispassed by descriptor).*userPasswordVMS Usage: pointeurtype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the user password (on Unix and Windowsthe string ends by a null character, on OpenVMS the string is passed bydescriptor).*userAccountStructureVMS Usage: pointertype: pointer to structureaccess: write onlymechanism: by referencePointer to a UserAccountStructure type structure receiving the user accountcharacteristics.DESCRIPTIONThis function returns the detailed information concerning an account.A non-privileged account may read its own account status. A privilegedaccount granted the "group management" privilege may obtain the detailedinformation for all subaccount depending of its master company account.RETURNVALUESSMSNormalSMSNoPrivilegeSMSInvalidLoginInfoSMSInvalidUseridSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterUser account found and data returned.the access rights of the caller account do not allow toaccess this account.Either companyId or password are invalid,authentication rejected.the specified userId is invalid.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.EXAMPLESExample8–5

Management functionsSMS_ModifyAccountSMS_ModifyAccount—Modify an existing accountThis function is used to modify an existing account.FORMAT SMS_ModifyAccount UInt32 *ConnectId, structure*UserAccountStructureRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*userAccountStructureVMS Usage: pointertype: pointer to structureaccess: read onlymechanism: by referencePointer to a UserAccountStructure type structure storing the updated useraccount characteristics.DESCRIPTIONThis function is used to modify an existing account. It must be calledafter prior authentication using the user account to be modified. TheUserAccountStructure structure filled in by the function SMS_GetAccountInfomay be then modified and used to supply the updated information.Some restrictions applies to the kind of data that could be modified:• accounting information such account credit and user privileges couldnever be modified.• account non sensitive information could be modified.RETURNVALUESSMSNormalSMSNoPrivilegeSMSErrorThis user account has been modified.The access rights of the caller account do not allowaccount creation operation.an unspecified error occurred.8–6

Management functionsSMS_ModifyAccountSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSMissingParameterSMSAccountNotExistthe link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.one of the mandatory parameters of theUserAccountStructure is not filled in.this account does not exist.EXAMPLESExample8–7

Management functionsSMS_IssueVoucherSMS_IssueVoucher—Issue a SMS voucherThis function issue a SMS voucher that could be used to credit another SMSaccount with the voucher value.FORMAT SMS_IssueVoucher UInt32 *ConnectId, Int32*NbrCredits, char *VoucherIdRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*NbrCreditsVMS Usage: pointertype: pointer to signed longwordaccess: read onlymechanism: by referencePointer to positive signed longword storing the voucher value in amount ofSMS units.*VoucherIdVMS Usage: pointertype: pointer to a 20-characters stringaccess: write onlymechanism: by referencePointer to a 20-characters string receiving the unique voucher ID returned bythe function.DESCRIPTIONThis function will generate a voucher (SMS check) that could be cashed byanother SMS account. The amount of the voucher issued will be decrementedfrom the issuer account balance.This function must be called after prior authentication using the issuer account.8–8

Management functionsSMS_IssueVoucherRETURNVALUESSMSNormalSMSNoPrivilegeSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSMissingParameterSMSAccountNotExistSMSUserIdLockedSMSCompanyIdLockedSMSQuotaExceededThe requested voucher has been issued.The access rights of the caller account do not allow toissue a voucher.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.one of the mandatory parameters is not filled in.this account does not exist.this user account is locked.this company account is locked.there is not enough SMS units remaining on theaccount balance of the issuer to generate a voucherof such an amount.EXAMPLESExample8–9

Management functionsSMS_RedeemVoucherSMS_RedeemVoucher—Cash a SMS voucherThis function request the cashing of a valid SMS voucher, to be credited tothe user account.FORMAT SMS_RedeemVoucher UInt32 *ConnectId, Int32*NbrCredits, char *VoucherIdRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*NbrCreditsVMS Usage: pointertype: pointer to signed longwordaccess: write onlymechanism: by referencePointer to positive signed longword receiving the voucher value in amount ofSMS units.*VoucherIdVMS Usage: pointertype: pointer to a 20-characters stringaccess: read onlymechanism: by referencePointer to a 20-characters string storing the voucher ID to be cashed.DESCRIPTIONThis function allows an user account to cash a SMS voucher previouslygenerated by another account. It must be called after authentication on theaccount to be credited.After cashing, the voucher is definitely void.8–10

Management functionsSMS_RedeemVoucherRETURNVALUESSMSNormalSMSNoPrivilegeSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSMissingParameterSMSUserIdLockedSMSCompanyIdLockedSMSVoucherInvalidSMSVoucherAlreadySpentThe voucher has been cashed and voided, useraccount has been credited of NbrCredits SMS units.The access rights of the caller account do not allow tocash a voucher.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.one of the mandatory parameters is not filled in.this user account is locked.this company account is locked.this voucher identifier is invalid.this voucher has already been cashed and is void.EXAMPLESExample8–11

Management functionsSMS_ResendPasswordSMS_ResendPassword—Send again a lost passwordto the userThis function sends again its lost password to an existing user account, eitherby email or by SMS.FORMAT SMS_ResendPassword UInt32 *ConnectId, char*CompanyId, char *UserIdRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.*companyIdVMS Usage: pointertype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the company user identification (on Unixand Windows the string ends by a null character, on OpenVMS the string ispassed by descriptor).*userIdVMS Usage: pointertype: pointer to character stringaccess: read onlymechanism: by referencePointer to a character string storing the user identification (username) (on Unixand Windows the string ends by a null character, on OpenVMS the string ispassed by descriptor).DESCRIPTIONThis function is used to send again to an user its password in case of lostpassword.No prior authentication is needed (as the user has lost its password, it isunable to identify itself and has only to specify its companyname/username.8–12

Management functionsSMS_ResendPasswordThe password will be sent again using either SMS or email to the user mobileMSISDN number or email address stored in its account profile (default is SMSsending to mobile for additional safety and reliable user authentication).To prevent abuses, the number of allowed lost password sending operation islimited.RETURNVALUESSMSNormalSMSNoPrivilegeSMSErrorSMSLinkLostSMSNoVideosmsSMSInvalidParameterSMSMissingParameterSMSUserIdLockedSMSCompanyIdLockedSMSAccountNotExistSMSTooManyResendPwdThe password has been resent to the user.The access rights of the caller account do not allow tocall this function.an unspecified error occurred.the link to the MCTEL SMS Gateway has been lost.VIDEOSMS is not installed on this system.one of the specified parameter is invalid.one of the mandatory parameters is not filled in.this user account is locked.this company account is locked.this user account does not exist.the maximum number of password resend operationsfor this account has been reachedEXAMPLESExample8–13

Management functionsSMS_GetProcessedMessageSMS_GetProcessedMessage—Return previouslyprocessed messagesThis function returns one after the other all previously processed messages(received or sent) for this application/user.FORMAT SMS_GetProcessedMessage UInt32 *ConnectId,Uint32 *msgtype,Uint32 *msgoptions,SMSMessage*SMSMessageRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.msgtypeVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceMessage type to be retrieved:1 SMS sent.2 SMS received and application-processed. New unprocessed incomingmessages are not returned by this function but with SMS_Read function.msgoptionsVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceOptions: the following bits may be set to specify options:8–14

Management functionsSMS_GetProcessedMessage• 0: full data: in this case the whole message details are retrievedand returned. If this bit is not set and in order to increase networkperformance, only the following data will be returned:5 msg_reference_number: message reference number5 called_number: called number5 caller_number: caller number5 sms_state: message state5 sms_error: transmission error code if applicable.5 posted_date: SMS submission date.5 transmitted_date: SMS reception date or final error date.• 1: get next: if this bit is set and the function has been called previously,the function will return either the next message in the log or an error ifthere is no more message. The previous SMS_GetProcessedMessagefunction call must have been called with the bit 2 of the msgoptions fieldset.• 2: expect next: if a message is retrieved, the calling program will performanother request with bit 1 set (get next option). The bit 2 will ask thegateway to keep the search context.• 3: return also charging data: if this bit is set, the function will also returnthe charging information regarding this message: charge, credit or otheroperation.*SMSMessageVMS Usage: pointertype: pointer to a SMSMessage structureaccess: write onlymechanism: by referencePointer to a SMSMessage structure returning the complete message data (ifbit 0 full data is set).DESCRIPTIONThis function retrieve and returns all incoming or outgoing messagesprocessed by the user or application. There is no need to know the messagereference numbers to retrieve them. This function must be called afterprevious user identification.RETURNVALUESSMSNormalSMSNoMessageSMSNoPrivilegeSMSErrorSMSLinkLostSMSNoVideosmsa message has been found and is returned.no more message found.user access rights could not grant access to thisfunction.an error occured.the link with the remote SMS gateway has been lost.VIDEOSMS is not installed on this system.8–15

Management functionsSMS_GetProcessedMessageSMSNotConnectedSMSInvalidParameterthe application is not connected to the SMS gateway.one of the specified parameters is invalid.EXAMPLESExample8–16

Management functionsSMS_GetAccountRecordSMS_GetAccountRecord—Retrieve account chargingdataThis function retrieves and returns one per one all the user account chargingrecords.FORMAT SMS_GetAccountRecord UInt32 *ConnectId,Uint32 *msgtype,Uint32 *msgoptions,SMSChargingData*SMSChargingDataRETURNSVMS Usage: cond_valuetype: longwordaccess: read onlymechanism: by valueARGUMENTSConnectIdVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceUnique connection id, initialized by the function SMS_ConnectGateway.Type of charging records to retrieve:1 0: all records.2 n: charging records of type n.msgoptionsVMS Usage: pointertype: pointer to longwordaccess: read onlymechanism: by referenceOptions: the following bits may be set to specify options:• 1: get next: if this bit is set and the function has been called previously,the function will return either the next record in the charging data file or anerror if there is no more record. The previous SMS_GetAccountRecordfunction call must have been called with the bit 2 of the msgoptions fieldset.• 2: expect next: if a record is retrieved, the calling program will performanother request with bit 1 set (get next option). The bit 2 will ask thegateway to keep the search context.8–17

Management functionsSMS_GetAccountRecord*SMSChargingDataVMS Usage: pointertype: pointer to a SMSChargingData structureaccess: write onlymechanism: by referencePointer to a SMSChargingData type structure storing the retrieved chargingrecord.DESCRIPTIONThis function retrieves and returns one per one all the user account chargingrecords.RETURNVALUESSMSNormalSMSNoMessageSMSNoPrivilegeSMSErrorSMSLinkLostSMSNoVideosmsSMSNotConnectedSMSInvalidParametera charging record has been found and is returned.no more charging record found.user access rights could not grant access to thisfunction.an error occured.the link with the remote SMS gateway has been lost.VIDEOSMS is not installed on this system.the application is not connected to the SMS gateway.one of the specified parameters is invalid.EXAMPLESExample8–18

9Examples9.1 Visual Basic SMS send programThis Visual Basic program will send a SMS and check in real time itstransmission status.Example 9–1Visual Basic SMS send exampleVERSION 5.00Begin VB.Form DemoFormCaption = "Demo SMS API - MCTEL"ClientHeight = 3105ClientLeft = 60ClientTop = 450ClientWidth = 7560LinkTopic = "Form1"ScaleHeight = 3105ScaleWidth = 7560StartUpPosition = 3 ’Windows DefaultBegin VB.TextBox MotDePasseHeight = 375IMEMode = 3 ’DISABLELeft = 1440PasswordChar = "*"TabIndex = 2Top = 675Width = 1695EndBegin VB.TextBox CompteHeight = 375Left = 1440TabIndex = 1Top = 200Width = 1695EndBegin VB.CommandButton BtStatutCaption = "Request status for last send"Height = 495Left = 4560TabIndex = 5Top = 840Width = 2295EndBegin VB.TextBox NumeroHeight = 375Left = 1920TabIndex = 3Text = "+336"Top = 1515Width = 1575EndBegin VB.CommandButton BtEnvoyerCaption = "Send test message"Height = 495Left = 720Example 9–1 Cont’d on next page9–1

ExamplesExample 9–1 (Cont.)Visual Basic SMS send exampleTabIndex = 4Top = 2040Width = 2295EndBegin VB.Line Line2X1 = 0X2 = 7560Y1 = 2760Y2 = 2760EndBegin VB.Label Label5Caption = "Password :"Height = 255Left = 120TabIndex = 12Top = 720Width = 1095EndBegin VB.Label Label4Caption = "Account :"Height = 255Left = 120TabIndex = 11Top = 240Width = 855EndBegin VB.Label Label3Caption = "SMS status :"Height = 255Left = 3960TabIndex = 10Top = 1680Width = 1215EndBegin VB.Label RefDernierMessageCaption = "?"Height = 255Left = 3960TabIndex = 9Top = 360Width = 3495EndBegin VB.Label Label2Caption = "Ref number of last send :"Height = 255Left = 3960TabIndex = 8Top = 120Width = 1935EndBegin VB.Line Line1X1 = 3720X2 = 3720Y1 = 0Y2 = 2760EndBegin VB.Label Label1Caption = "Recipient mobile number :"Height = 255Left = 120TabIndex = 7Top = 1560Width = 1695EndExample 9–1 Cont’d on next page9–2

ExamplesExample 9–1 (Cont.)Visual Basic SMS send exampleBegin VB.Label MsgStatusCaption = "?"Height = 255Left = 5160TabIndex = 6Top = 1680Width = 2295EndBegin VB.Label TraceCaption = "Ready"Height = 255Left = 120TabIndex = 0Top = 2880Width = 7335EndEndAttribute VB_Name = "DemoForm"Attribute VB_GlobalNameSpace = FalseAttribute VB_Creatable = FalseAttribute VB_PredeclaredId = TrueAttribute VB_Exposed = False’=============================================================’ API SMS Demo Program’’-------------------------------------------------------------’ Author: Eric LOKHATE’ Copyright (C) 2004-2005 Monaco Telematique / MCTEL-SAM’=============================================================’’ NOTES :’ 1/ Please check the sms API is imported in VB references:’ Go to "Project | References..." mneu. Check the library’ "MCTEL smsApi" is listed amongst reference list and checked.’ If this is not the case, click on "Parse..." and select’ the smsApi.TLB file to import the library.’’ 2/ Once the library is imported, you could list all imported’ symbols using the Object Explorer (key F2 or use the’ "Display | Object Explorer" menu)’ You will find there the calling syntax for all functions.’’ 3/ At runtime the executable program will need the smsApi.dll to run:’ - IN COMPILATION MODE :’ - smsApi.dll must be stored in the same directory than the calling’ .exe executable file.’ - IN INTERPRETED MODE :’ - smsApi.dll must be stored in a directory listed in the PATH’ (e.g.:c:\windows\systeme32)’ - smsApi.tlb must be stored in the same directory than the program’ or from VBA (MSAccess) in the database directory.’’-----------------------------------------------------------------------------------’ Copy ’Src’ string (format VB) to character array ’Dest’ (format C)’ adding the ’0’ endstring’-----------------------------------------------------------------------------------Private Sub CopyVBStringToCString(ByVal Src As String, ByRef Dest() As Byte)Example 9–1 Cont’d on next page9–3

ExamplesExample 9–1 (Cont.)Visual Basic SMS send exampleDim iLg = Len(Src)For i = 1 To Lg Step 1cc = Mid(Src, i, 1)Dest(i - 1) = Asc(cc)NextDest(Lg) = 0End Sub’-----------------------------------------------------------------------------------’ Returns a copy of the ’Src’ character array (format C) as character string’ (format VB)’-----------------------------------------------------------------------------------Private Function CopyCStringToVBString(ByRef Src() As Byte) As StringDim iDim Dest As Stringi = 0Do While Src(i) 0Dest = Dest + Chr(Src(i))i = i + 1LoopCopyCStringToVBString = DestEnd Function’ ======================’ Example of SMS sending’ ======================Private Sub BtEnvoyer_Click()Dim Ret As smsRetDim ConnID As LongDim GatewayAddress As StringDim GatewayAddressLen As LongDim Port As LongDim NbrCredits As LongDim SoftVersion As StringTrace.Caption = "Connection in progress..."Ret = 0’-------------------------------------------------------------’ Connecting to MCTEL SMS Gateway’-------------------------------------------------------------GatewayAddress = "smssmpp.mctel.fr"GatewayAddressLen = Len(GatewayAddress)Port = 80Ret = SMS_ConnectGateway(ConnID, _GatewayAddress, _GatewayAddressLen, _Port)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_ConnectGateway : " + Str(Ret)MsgBox (Trace.Caption)Exit SubEnd IfTrace.Caption = "SMS_ConnectGateway OK"Example 9–1 Cont’d on next page9–4

ExamplesExample 9–1 (Cont.)Visual Basic SMS send example’-------------------------------------------------------------’ Identification’-------------------------------------------------------------CompanyID = "MCTELWEBSMS"CompanyPwd = "0yZt78w"UserID = UCase(Compte.Text)UserPwd = MotDePasse.TextSoftVersion = "DEMO"Ret = SMS_LoginGateway(ConnID, _CompanyID, CompanyPwd, _UserID, UserPwd, _SoftVersion, _SMSLoginOpt_None, _NbrCredits)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_LoginGateway : " + Str(Ret)MsgBox (Trace.Caption)Exit SubEnd IfTrace.Caption = "SMS_LoginGateway OK"’-------------------------------------------------------------’ Sending the message’-------------------------------------------------------------Dim Msg As StringDim MsgStruct As SMSMessageNumDest = Numero.TextMsg = "This is my test message from VB."Call CopyVBStringToCString("06000000", MsgStruct.caller_number)Call CopyVBStringToCString(NumDest, MsgStruct.called_number)MsgStruct.msg_length = Len(Msg)Call CopyVBStringToCString(Msg, MsgStruct.msg_data)MsgStruct.msg_class = 1’ Initialize if necessary the sending options’ (SMSOpt_Deferred, SMSOpt_EmailAlert, SMSOpt_EmailConfirm, SMSOpt_Flash,’ SMSOpt_Confidential)MsgStruct.msg_options = 0’ Set deferred date if "SMSOpt_Deferred" is set in "msg_options"’ elsewise left to 0MsgStruct.deferred_date = 0Ret = SMS_Send(ConnID, MsgStruct, "", "")If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_Send : " + Str(Ret)MsgBox (Trace.Caption)ElseRefDernierMessage.Caption = CopyCStringToVBString(MsgStruct.msg_reference_number)Trace.Caption = "SMS_Send OK" + RefDernierMessage.CaptionEnd If’-------------------------------------------------------------’ Close session’-------------------------------------------------------------Ret = SMS_LogoutGateway(ConnID)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_LogoutGateway"MsgBox (Trace.Caption)Exit SubEnd IfTrace.Caption = "SMS_LogoutGateway OK"Example 9–1 Cont’d on next page9–5

ExamplesExample 9–1 (Cont.)Visual Basic SMS send example’-------------------------------------------------------------’ Disconnect from MCTEL SMS Gateway’-------------------------------------------------------------Ret = SMS_DisconnectGateway(ConnID)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_DisconnectGateway : " + Str(Ret)MsgBox (Trace.Caption)Exit SubEnd IfTrace.Caption = "SMS_DisconnectGateway OK"Trace.Caption = "SMS Sending completed."End Sub’ =======================================’ Example of SMS status real-time request’ =======================================Private Sub BtStatut_Click()If RefDernierMessage.Caption = "?" ThenExit SubEnd IfDim Ret As smsRetDim ConnID As LongDim SoftVersion As StringDim NbrCredits As LongTrace.Caption = "Connect in progress..."’-------------------------------------------------------------’ Connection to MCTEL SMS Gateway’-------------------------------------------------------------GatewayAddress = "smssmpp.mctel.fr"GatewayAddressLen = Len(GatewayAddress)Port = 80Ret = SMS_ConnectGateway(ConnID, _GatewayAddress, _GatewayAddressLen, _Port)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_ConnectGateway : " + Str(Ret)MsgBox (Trace.Caption)Exit SubEnd IfTrace.Caption = "SMS_ConnectGateway OK"’-------------------------------------------------------------’ Identification’-------------------------------------------------------------CompanyID = "MCTELWEBSMS"CompanyPwd = "0yZt78w"UserID = UCase(Compte.Text)UserPwd = MotDePasse.TextSoftVersion = "DEMO"Example 9–1 Cont’d on next page9–6

ExamplesExample 9–1 (Cont.)Visual Basic SMS send exampleRet = SMS_LoginGateway(ConnID, _CompanyID, CompanyPwd, _UserID, UserPwd, _SoftVersion, _SMSLoginOpt_None, _NbrCredits)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_LoginGateway : " + Str(Ret)MsgBox (Trace.Caption)Exit SubEnd IfTrace.Caption = "SMS_LoginGateway OK"’-------------------------------------------------------------’ Retrieve SMS message status in real-time’-------------------------------------------------------------Dim MsgStruct As SMSMessageDim PrivateRef As StringDim PrivateData As StringCall CopyVBStringToCString(RefDernierMessage.Caption, MsgStruct.msg_reference_number)PrivateRef = ""PrivateData = ""Ret = SMS_ReadStatus(ConnID, MsgStruct, PrivateRef, PrivateData)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_ReadStatus : " + Str(Ret)MsgStatus.Caption = Trace.CaptionMsgBox (Trace.Caption)ElseTrace.Caption = "SMS_ReadStatus OK"MsgStatus.Caption = Str(MsgStruct.sms_state)’ According to the value of "MsgStruct.sms_state" perform the.’ appropriate actions (e.g. display message)’End If’-------------------------------------------------------------’ Close session’-------------------------------------------------------------Ret = SMS_LogoutGateway(ConnID)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_LogoutGateway"MsgBox (Trace.Caption)Exit SubEnd IfTrace.Caption = "SMS_LogoutGateway OK"’-------------------------------------------------------------’ Disconnect from SMS Gateway’-------------------------------------------------------------Ret = SMS_DisconnectGateway(ConnID)If (Ret SMSNormal) ThenTrace.Caption = "Error SMS_DisconnectGateway : " + Str(Ret)MsgBox (Trace.Caption)Exit SubEnd IfTrace.Caption = "SMS_DisconnectGateway OK"Trace.Caption = "End of request."End SubExample 9–1 Cont’d on next page9–7

ExamplesExample 9–1 (Cont.)Visual Basic SMS send examplePrivate Sub Form_Load()’ To fill in with the user account information’’Compte.Text = "my account"’MotDePasse.Text = "my password"End Sub9.2 Linux C SMS Send program exampleThis C program sends a SMS and allows to check in real time its successfultransmission.Example 9–2C SMS Send sample progral/*Sample C program demonstrating SMS MCTEL APINote: this file must be linked with smsApi-linux.a object file*/#include "smsApi.h"#include #include //------------------------------------------------------------------------#define COMPANYID "My_CompanyId"#define COMPANYPWD "My_CompanyPwd"#define USERID "My_UserId"#define USERPWD "My_UserPwd"//------------------------------------------------------------------------smsRet ConnectToSMSServer(char* AppName,smsConnID* ConnId,char* CompanyId,char* CompanyPwd,char* UserId,char* UserPwd,smsUInt32* NbCredits)/*Open a connection to the SMS Gateway and authenticate user using ’UserId’and ’UserPwd’If ’CompanyId’ and ’CompanyPwd’ are !=0, they will be used for authentication’AppName’ is the name of the calling application (freeform).Returns the status sent by the server.*/{return Res;}//------------------------------------------------------------------------int main(int argc, char *argv[]) {Example 9–2 Cont’d on next page9–8

ExamplesExample 9–2 (Cont.)C SMS Send sample progralsmsRet Res;smsConnID ConnId;smsUInt32 NbCredits;SMSMessage Message;char PrivateReference[SMS_SEND_PRIVATE_REF_MAX_LEN]="My ref";char PrivateData[SMS_SEND_PRIVATE_DATA_MAX_LEN]="xxx";/* Connection to MCTEL SMS Gateway */Res = SMS_ConnectGateway( &ConnId, GATEWAY_ADDRESS, strlen(GATEWAY_ADDRESS),GATEWAY_PORT );if(Res!=SMSNormal) {printf("Connection error to MCTEL SMS Gateway.\n");return Res;}/* Identification */Res = SMS_LoginGateway( *ConnId, COMPANYID, COMPANYPWD, USERID, USERPWD,"MONAPP", 0, &NbCredits );if ( Res != SMSNormal ) {SMS_LogoutGateway( *ConnId );printf("Authentication failure.\n");return Res;}/*Fill in HERE the ’Message’ structure*/memset(&Message, 0, sizeof(Message));strcpy(Message.called_number, "+336xxxx");strcpy(Message.caller_number, "+336xxxx");strcpy(Message.msg_data, "This is my test message from linux.");Message.msg_length = (smsUInt32) strlen(Message.msg_data);Message.msg_class = 1;//Initialize send options://(SMSOpt_Deferred, SMSOpt_EmailAlert, SMSOpt_EmailConfirm, SMSOpt_Flash,//SMSOpt_Confidential)Message.msg_options = SMSSendOpt_None;//Initialize deferred date if "SMSOpt_Deferred" is set in "msg_options"//elsewise put 0Message.deferred_date = 0;/* Send the SMS */Res = SMS_Send(ConnId, &Message, PrivateReference, PrivateData);if(Res!=SMSNormal) {printf("Error sending SMS to MCTEL gateway.\n");return;}printf("Message sent.\n");/* Disconnect */SMS_LogoutGateway( ConnId );SMS_DisconnectGateway( ConnId );}9–9

IndexAAccountcreation • 8–2modification • 8–6read data • 8–4Alphabet • 3–9CCDexample • 9–8link • 2–1Disconnectionfrom SMS Gateway • 4–9DLL • 2–1EErrorsduring transmission • 3–11status • 3–10ETSIStandards • vGGatewayconnect • 4–2disconnect • 4–9login • 4–4logout • 4–7HHandsetretrieval • 6–6IIMEI • 3–7LLinuxexample • 9–8Location positioning • 6–2Location positionning • 3–5MMessagegetting • 5–15reading status • 5–12sending • 5–2type • 3–8MNC • 3–6NNCC • 3–6OOpenVMSlink • 2–2Operatorretrieval • 6–4Index–1

IndexPPasswordresend • 8–12Programming • 2–1SSMPPtime • 3–12SMSalphabet encoding • 3–9format • 3–9type • 3–8SMSChargingData • 3–4SMSDateTimeType • 3–8SMSHandset • 3–7SMSMessage • 3–1SMSOperator • 3–6SMSReport • 3–5SMSSession • 3–1SMSUserAccountInfo • 3–2SMSUserLocation • 3–5SMS_ConnectGateway • 4–2SMS_CreateAccount • 8–2SMS_DisconnectGateway • 4–9SMS_EnquireLink • 4–8SMS_FindHandsetInfo • 6–6SMS_FindOperator • 6–4SMS_GetAccountInfo • 8–4SMS_GetAccountRecord • 8–17SMS_GetLocation • 6–2SMS_GetMessage • 5–15SMS_GetProcessedMessage • 8–14SMS_GetSessionData • 7–6SMS_GetSessionInfo • 7–4SMS_IssueVoucher • 8–8SMS_LoginGateway • 4–4SMS_LogoutGateway • 4–7SMS_ModifyAccount • 8–6SMS_Read • 7–2SMS_ReadStatus • 5–12SMS_RedeemVoucher • 8–10SMS_Reply • 7–10SMS_ResendPassword • 8–12SMS_Send • 5–2SMS_UpdateSessionData • 7–8SMS_WapPush • 5–7StructureSMSChargingData • 3–4SMSHandset • 3–7SMSMessage • 3–1SMSOperator • 3–6SMSReport • 3–5SMSSession • 3–1SMSUserAccountInfo • 3–2SMSUserLocation • 3–5WapData • 3–6TTAC • 3–7Text To Speech • 3–9Timeformat • 3–12UUnixexample • 9–8link • 2–2supported releases • 2–1Userlocation • 3–5VVisual Basicexample • 9–1link • 2–1Visual C++link • 2–1Voucherissue • 8–8redeem • 8–10WIndex–2

IndexWapData • 3–6Wap Pushsending • 5–7WapData structure • 3–6Windowsenvironment • 2–1Index–3