The Send Call File Service sends a media file(s) to the user. The user needs to be logged in and authorized for each file requested. All files are retrieved using a Download Token. If the file is an unmixed .recd, mixing must be requested before the file(s) can be sent. See the Encode recd file output format in this Service for details.

All requests are treated the same way, as there is no way to differentiate between a request received from a media player or from a browser, due to the wide spectrum of embedded and standalone players used (for example: QuickTime, Windows Media Player, Advanced Player).

Service Pre-requisites

The service requires:

  • The JSESSIONID obtained from the Log In Service.
  • A token from the Download Token Service :
    • Provides an authorization mechanism
    • The token contains data associated with the search criteria

Service Invocation

An HTTP POST method must be addressed to the following URL:

http://<server>/callrec/sendcallfile.mp3

 Input Parameters

The service expects to receive:

  • The download token, as follows: token=<token>
  • The previously obtained JSESSIONID to identify the user in the form of:
    • A cookie
    • An append to the URL immediately after the servlet name, as follows: jsessionid=<sessionid>

Parameters for Download Token Service

When requesting a token from the Download Token Service, search criteria must be specified. The search criteria are dependent on the service that will be invoked afterwards. In the case of the Send Call File Service, the relevant search parameters are:

  • id_call[] - An array of couple IDs
  • sid - Couple SID. If specified, id_call[] is ignored
  • type - requested media type. 1 - call, 16 - video. This determines the permissions required
  • action - specifies the intended action. This determines the permissions required:
    • download - call file(s) will be sent to the client
    • prepare - encode .recd file into video with audio
    • <any other value or nothing> - stream playback is assumed

 Output

The response format depends on the combination of parameters passed to the servlet.

  • Audio stream

    An audio stream is returned under the following conditions:

    • sid is specified, or call_id[] with a single value
    • type = 1
    • action is not specified or not download
  • Video stream

    A video stream is returned under the following conditions:

    • sid is specified, or call_id[] with a single value
    • type = 16
    • action is not specified or not download
  • Encode .recd file

    Encodes and mixes a .recd file with the corresponding calls and returns a new download token after the encoding is finished.

    • sid is specified, or call_id[] with a single value
    • type = 16
    • action is prepare
  • Single media file

    A single media file is returned under these conditions:

    • sid or call_id[] is specified
    • action is download
    • The media file is returned as an attachment in the format it has been recorded in
  • Multiple media files

    Multiple media files are returned under these conditions:

    • call_id[] contains multiple couple IDs
    • action is download
    • The files are returned in a .zip archive with an enclosed text file describing its contents

Additionally, the Service will return an HTTP status, such as:

  • 200: if the operation was successful
  • 403: if the token was non-existent or already used
  • 302: if the session expired

Example for Requesting a Media File with the Send Call File Service

Now that we have the download token, the Send Call File Service can be called:

With Firefox:

Enter the following URL into the browser to invoke the Send Call File Service (substituting in the download token obtained):

http://<server>/callrec/sendcallfile.mp3;jsessionid=<
jsessionid>?token=<download_token>

The server will respond by sending a zip containing the requested media files, triggering the browser to display the file open/save dialog.

With cURL:

Invoke the Send Call Service with the following request:

curl -v -b cookies.txt -c cookies.txt -X POST -d "token=<download_token>" \
-H"Content-Type: application/x-www-form-urlencoded" -H"Accept: application/octet-stream" \
-o file.zip http://<server>/callrec/sendcallfile.mp3

The server will respond with a zip containing the requested media files:

* About to connect() to myserver port 80 (#0)
* Trying 10.0.0.1... % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0connected
* Connected to myserver (10.0.0.1) port 80 (#0)
> POST /callrec/sendcallfile.mp3 HTTP/1.1
> User-Agent: curl/7.21.0 (x86_64-pc-linux-gnu) libcurl/7.21.0 OpenSSL/0.9.8o zlib/1.2.3.4 libidn/1.18
> Host: myserver
> Cookie: JSESSIONID=8A355EC61B5D804447704B8CB64DF535
> Content-Type: application/x-www-form-urlencoded
> Accept: application/octet-stream
> Content-Length: 26
> } [data not shown]
< HTTP/1.1 200 OK
< Server: Apache-Coyote/1.1
< Content-Disposition: attachment; filename=calldata.zip
< Content-Type: application/zip;
< Transfer-Encoding: chunked
< Date: Fri, 20 May 2011 13:55:18 GMT
< { [data not shown]
100 40521 0 40521 0 26 440k 289 --:--:-- --:--:-- --:--:-- 454k
* Connection #0 to host myserver left intact
* Closing connection #0

See the description of the Send Call File Service  for more details about valid search parameters.