<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Service_OrangeApi Component Proposal

Table of Contents

1. Overview

Orange API provide to web developers and integrators, a set of web services allowing to easily integrate telecom services into web sites and applications.
The Orange APIs, available on Orange APIs, are currently the following :

• sending and receiving text messages services (Send SMS) to any operator worldwide and multimedia messages (send MMS) to Orange mobile phones.
• get the location of Orange mobile phones, for any device
• call-control service
• conference management
• interactive vocal services

The Zend_Service_OrangeApi components provides a clean and simple interface to the » Orange APIs and additionally offers functionality
to improve handling and performance.

In order to make such APIs easy to use for Zend developers, Orange supplies a core Zend component.

2. References

• Orange API Website

3. Component Requirements, Constraints, and Acceptance Criteria

• This component wraps Orange APis in a raw manner (i.e parameters names, methods names, returned values)
• This component is as exhaustive as possible, regarding APIs functionalities.
• This component does not include parameters validity control, it will be done on the server side.
• This component relay server-side returned errors by throwing exceptions, containing errors codes and errors messages.
• This component allow subclassing, for any useful purpose.

4. Dependencies on Other Framework Components

• Zend_Http_Client_Adapter_Proxy
• Zend_Rest_Client
• Zend_Service_Exception

5. Theory of Operation

Every Orange API is accessed through a single class which inherits the common Zend_Service_OrangeApi_Client class.
Each API class is named after the official Orange API denomination.
Each API class instanciation is done by passing the mandatory Orange access key ("id" parameter) to the constructor.

6. Milestones / Tasks

• Milestone 1: [DONE] Set a common architecture for all APIs
• Milestone 2: [DONE] Working prototype checked into the incubator supporting use cases.
• Milestone 4: [DONE] Initial documentation exists.

7. Class Index

• Zend_Service_OrangeApi_ClientAbstract
• Zend_Service_OrangeApi_Exception
• Zend_Service_OrangeApi_ClickToCall
• Zend_Service_OrangeApi_ClickToConf
• Zend_Service_OrangeApi_History
• Zend_Service_OrangeApi_Mms
• Zend_Service_OrangeApi_Sms
• Zend_Service_OrangeApi_Location
• Zend_Service_OrangeApi_VoiceMashup

8. Use Cases

Send an SMS using Zend Orange API

Ask a mobile user to accept geolocation using Zend Orange API

//Zend_Service_OrangeApi_Location inititialization
$location =new Zend_Service_OrangeApi_Location( $accessKey );

/**

• @desc create authorization
• @param number : Telephone number of mobile from which authorisation to be located is being requested.
• This number must be in international format.
  */

$location->createAuthorization($number);

}

//Zend_Service_OrangeApi_Location inititialization
$location =new Zend_Service_OrangeApi_Location( $accessKey );

/**

• @desc getLocation
• @param getLocNumber : Telephone number of the mobile to be located in international format.
  */

$location->getLocation($getLocNumber);

Create a phone conference using Zend Orange API

//Zend_Service_OrangeApi_ClickToConf initialization
$clickToConf =new Zend_Service_OrangeApi_ClickToConf( $accessKey );

/**

• @desc createConference
• @param accesMode :
• room : Limiting access to the conference by a code
• caller : Limiting access to the conference by a list of authorised telephone numbers
• room+caller : Limiting access to the conference by a code and a list of authorised telephone numbers
• none : The conference can only call each participant by invoking the createCall method
• @param callers (optional): List of numbers authorised to enter the conference.
• @param duration (optional): Language used when confirmation is enabled.
• @param when (optional): Conference start date and time.
• @param greeting (optional): Language of conference welcome greeting+ activation of an alert when a new participant dials in (for people already on the conference).
  */

$clickToConf->createConference( $accesMode,
$callers,
$duration,
$when,
$greeting
);

//Zend_Service_OrangeApi_ClickToConf init
$clickToConf =new Zend_Service_OrangeApi_ClickToConf( $accessKey );

/**

• @desc AddCaller
• @param conferenceId : Conference unique ID (obtained by calling the "createConference" method).
• @param addCallerNumbers : List of telephone numbers authorised to join the conference.
  */
  $clickToConf->addCaller( $conferenceId,
  $addCallerNumbers
  );

  //Zend_Service_OrangeApi_ClickToConf inititialization
  $clickToConf =new Zend_Service_OrangeApi_ClickToConf( $accessKey );

/**

• @desc createcall
• @param callers : Telephone numbers in international format.
• @param conferenceId : Conference unique ID (obtained by calling the "createConference" method).
• @param notificationUrl (optional): An URL to receive real time information about the call.
  */
  $clickToConf->createCall( $callers,
  $conferenceId,
  $notificationUrl
  );

  //Zend_Service_OrangeApi_History inititialization
  $history =new Zend_Service_OrangeApi_History( $accessKey );

/**

• @desc getHistory
• @param offset (optional): Specify where to start the history.
• @param maxRows (optional): Specify the lines maximum number.
• @param callId (optional): Allows users to get history on a specific identifier.
• @param child_id (optional): Allows users to get history on an child accessKey.
  */

$history->createCall($offset,
$maxRows,
$callId,
$child_id
);

//Zend_Service_OrangeApi_VoiceMashup inititialization
$VoiceMashup =new Zend_Service_OrangeApi_VoiceMashup( $accessKey );

/**

• @desc voiceMashup
• @param to : The phone number to call, and send the vocal message.
• @param url : The URL where the VXML file is stored, containing the text to be heard.

• */
  $VoiceMashup->voiceMashup($to,$url);

9. Class Skeletons

Zend_Service_OrangeApi_ClientAbstract

Zend_Service_OrangeApi_Exception

Zend_Service_OrangeApi_Sms

Zend_Service_OrangeApi_ClickToCall

Zend_Service_OrangeApi_ClickToConf

Zend_Service_OrangeApi_Location