Thursday, 21 August 2014

Reading the response message from a PUT request using PHP and cURL

Previously I’ve mentioned that I had to write some PHP to PUT some JSON data to a RESTful web API. After calling curl_exec() to make the PUT request I called curl_getInfo() to retrieve the HTTP status code from the response message, in order to output a success or failure message.

While debugging this function it was sometimes necessary to examine the request message being sent to the web API, to ensure its format was correct. This required setting some additional CURLOPT parameters, as shown in the code below.

1 function callRestAPI($uri, $signature, $json) {
2 $headers = array (
3 "Content-Type: application/json; charset=utf-8",
4 "Content-Length: " .strlen($json),
5 "X-Signature: " . $signature
6 );
7
8 $channel = curl_init($uri);
9 curl_setopt($channel, CURLOPT_RETURNTRANSFER, true);
10 curl_setopt($channel, CURLOPT_CUSTOMREQUEST, "PUT");
11 curl_setopt($channel, CURLOPT_HTTPHEADER, $headers);
12 curl_setopt($channel, CURLOPT_POSTFIELDS, $json);
13 curl_setopt($channel, CURLOPT_SSL_VERIFYPEER, false);
14 curl_setopt($channel, CURLOPT_CONNECTTIMEOUT, 10);
15 curl_setopt($channel, CURLOPT_VERBOSE, true);
16 curl_setopt($channel, CURLOPT_HEADER, true);
17 curl_setopt($channel, CURLINFO_HEADER_OUT, true);
18
19 $response = curl_exec($channel);
20 $request = curl_getInfo($channel, CURLINFO_HEADER_OUT);
21 $statusCode = curl_getInfo($channel, CURLINFO_HTTP_CODE);
22
23 echo $request . "<BR>";
24 echo $response . "<BR>";
25 echo $statusCode . "<BR>";
26
27 curl_close($channel);
28 return $statusCode;
29 }

 

 

 

 

The additions are to set:

  1. CURLOPT_VERBOSE to true in order to output verbose information.
  2. CURLOPT_HEADER to true to include the header in the output.
  3. CURLINFO_HEADER_OUT to true to track the request message.

Then, after executing the PUT request I called curl_getInfo to get information about the PUT request. Specifically I requested the request message string by  using the CURLINFO_HEADER_OUT constant. This provides the request message which can then be output for debugging purposes.

Monday, 18 August 2014

Making a PUT request using PHP and cURL

I recently had to write some PHP to PUT some JSON data to a RESTful web API. My final solution involved reading numerous blog posts to piece together exactly what I needed. Bearing that in mind I decided to document my solution in case it’s useful to others, and for my own future use.

The conventional technique for invoking a PUT operation is to set CURLOPT_PUT to true. However, this option is used to PUT a file, with the file to PUT being set with CURLOPT_INFILE and CURLOPT_INFILESIZE. Using this approach involves writing your JSON data to a file first, and removing the file after the operation. Aside from the inefficiency of this approach, functions such as tmpfile(), fwrite() and fseek() are not always supported in some environments.

The standard solution is to set CURLOPT_CUSTOMREQUEST to “PUT” in order to specify the request type, and then set the CURLOPT_POSTFIELDS to the JSON data you want to PUT. In addition, you must set CURLOPT_RETURNTRANSFER to true in order to return the transfer value as a string, rather than it being output directly by curl_exec(). This is a well documented solution, most notably by LornaJane.

However, this solution needed extending in order to enable communication over SSL. In addition, I needed to append some custom header information to the request in order to support the authentication required by the web service. My solution is shown below.

1 function callRestAPI($uri, $signature, $json) {
2 $headers = array (
3 "Content-Type: application/json; charset=utf-8",
4 "Content-Length: " .strlen($json),
5 "X-Signature: " . $signature
6 );
7
8 $channel = curl_init($uri);
9 curl_setopt($channel, CURLOPT_RETURNTRANSFER, true);
10 curl_setopt($channel, CURLOPT_CUSTOMREQUEST, "PUT");
11 curl_setopt($channel, CURLOPT_HTTPHEADER, $headers);
12 curl_setopt($channel, CURLOPT_POSTFIELDS, $json);
13 curl_setopt($channel, CURLOPT_SSL_VERIFYPEER, false);
14 curl_setopt($channel, CURLOPT_CONNECTTIMEOUT, 10);
15
16 curl_exec($channel);
17 $statusCode = curl_getInfo($channel, CURLINFO_HTTP_CODE);
18 curl_close($channel);
19 return $statusCode;
20 }

The important additions are that I set:

  1. CURLOPT_SSL_VERIFYPEER to false to stop cURL from verifying the peer’s certificate, thus enabling communication over SSL. By default this value is true, and you are meant to set CURLOPT_CAINFO to specify the file holding the certificate to verify the peer with. I opted for stopping cURL from verifying the peer’s certificate in the interests of simplicity.
  2. CURLOPT_HTTPHEADER to an array of HTTP header fields, containing the data required by the web service, including an authentication parameter.

In addition, after executing the PUT request I called curl_getInfo to get information about the PUT request. Specifically I requested the status code of the operation using the CURLINFO_HTTP_CODE constant. This provides the HTTP status code contained within the response message, which is then returned to the calling function, so that an appropriate message can be output.

Monday, 4 August 2014

Delivering and consuming media from Azure Media Services

Previously I’ve summarised how to use the Azure Media Encoder to encode uploaded media for delivery to client apps. To do this you create a media processing job that enables you to schedule and automate the encoding of assets.

In this blog post I’ll summarise how Azure Media Services content can be downloaded, or directly accessed by using locator URLs. For more information about locator URLs see my previous blog post. Content to be delivered can include media assets that are stored in Media Services, or media assets that have been encoded and processed in different ways.

Delivering media

There are a number of approaches that can be used to deliver Media Services content:

  • Direct download from Azure Storage
  • Access media in Azure Storage
  • Stream media to a client application
  • Send media content to another application or to another content provider.

Media content can be directly downloaded as long as you have the Media Services credentials for the account that uploaded and encoded the asset. Content can be downloaded by creating a shared access signature (SAS) locator, which contains a URL to the asset that contains the requested file. The URL can then be used by anyone to download the asset.

Alternatively, you may want to give users access to content stored in Azure Storage. To do this you must create a full SAS URL to each file contained in the media asset. This is achieved by appending the file name to the SAS locator.

Media Services also provides the means to directly access streaming media content. This is accomplished by creating an on-demand origin locator, which allows direct access to streaming content. With on-demand origin locators, you build a full URL to a streaming manifest file in an asset. You then provide the URL to a client application that can play streaming content.

Content can also be delivered by using a Content Delivery Network (CDN), in order to offer improved performance and scalability when streaming media. For more information see How to Manage Origins in a Media Services Account.

When streaming media using on-demand origin locators you can take advantage of dynamic packaging. When using dynamic packaging, your video is stored in one encoded format, usually an adaptive bitrate MP4 file set. When a video player requests the video it specifies the format it requires, and the Media Services Origin Service converts the MP4 file to the format requested by the player. This allows you to store only one format of your videos, therefore reducing storage costs. For more information about the Origin Service see Azure Media Services Origin Service.

The following diagram shows a high-level overview of the media delivery process that we used in the Building an On-Demand Video Service with Microsoft Azure Media Services project.

IC721580

Client apps request media through a REST web interface. The Contoso web service queries the Content Management System, which returns the URL of the media asset in Azure Storage. The media asset could be a single media file, or a manifest file which references multiple media files. The client application then requests the URL content from the Origin Service, which processes the outbound stream from storage to client application. For a code walkthrough of this process see Browsing videos, Playing videos, and Retrieving recommendations.

You can scale Media Services delivery by specifying the number of on-demand streaming reserved units that you would like your account to be provisioned with. For more information see Scale a Media Service.

Summary

This blog post has summarised how Azure Media Services content can be downloaded, or directly accessed by using locator URLs. Content to be delivered can include media assets that are stored in Media Services, or media assets that have been encoded and processed in different ways.

Monday, 28 July 2014

Encoding and processing media in Azure Media Services

Previously I’ve summarised the media upload process from client apps into a video on-demand service that uses Azure Media Services.

In this blog post I’ll summarise how to incorporate Media Services’ encoding and processing functionality into an app. To do this you create processing jobs that enable you to schedule and automate the encoding and processing of assets.

Encoding and processing media

Media services provides a number of media processors that enable media to be processed. Media processors handle a specific processing task, such as encoding, format conversion, encrypting, or decrypting content. Encoding video is the most common Media Services processing operation, and is performed by the Azure Media Encoder. The Media Encoder is configured using encoder preset strings, with each preset specifying a group of settings required for the encoder. For a list of all the presets see Azure Media Encoder Presets.

Media Services supports progressive download of video and streaming. When encoding for progressive download you encode to a single bitrate. To be able to stream content it must first be converted into a streaming format. There are two types of streaming offered by Media Services:

  • Single bitrate streaming
  • Adaptive bitrate streaming

With single bitrate streaming a video is encoded to a single bitrate stream and divided into chunks. The stream is delivered to the client one chunk at a time. The chunk is displayed and the client then requests the next chunk. When encoding for adaptive bitrate streaming you encode to an MP4 bitrate set that creates a number of different bitrate streams. These streams are also broken into chunks. However, adaptive bitrate technologies allow the client to determine network conditions and select from among several bitrates. When network conditions degrade, the client can select a lower bitrate allowing the video to continue to play at a lower quality. Once network conditions improve the client can switch back to a higher bitrate with improved quality.

Media Services supports three adaptive bitrate streaming technologies:

  1. Smooth streaming, created by Microsoft
  2. HTTP Live Streaming (HLS), created by Apple
  3. MPEG-DASH, an ISO standard
Accessing media processors

Processing jobs involve calling a specific media process to process the job. Media Services supports the following media processors:

Media processor Description
Azure Media Encoder Allows you to run encoding tasks using the Media Encoder,
Azure Media Packager Allows you to convert media assets from MP4 to Smooth Streaming format, and Smooth Streaming assets to HLS format..
Azure Media Encryptor Allows you to encrypt media assets using PlayReady protection.
Storage Decryption Allows you to decrypt media assets that were encrypted using storage encryption.

To use a specific media processor you should pass the name of the processor into the GetLatestMediaProcessorByName method.

private IMediaProcessor GetLatestMediaProcessorByName(string mediaProcessorName)
{
    var processor = this.context.MediaProcessors.Where(p => p.Name == mediaProcessorName)
        .ToList().OrderBy(p => new Version(p.Version)).LastOrDefault();
 
    if (processor == null)
    {
        throw new ArgumentException(string.Format("Unknown media processor: {0}", mediaProcessorName));
    }
                
    return processor;
}

This method retrieves the specified media processor and returns an instance of it. It can be invoked as follows:

IMediaProcessor mediaProcessor = this.GetLatestMediaProcessorByName(MediaProcessorNames.WindowsAzureMediaEncoder);
Creating encoding jobs

After media has been uploaded into Media Services it can be encoded into one of the formats supported by the Media Services Encoder. The Media Services Encoder supports encoding using the H.264 and VC-1 codecs, and can generate MP4 and Smooth Streaming content. However, MP4 and Smooth Streaming content can be converted to HLS v3 or MPEG-DASH by using dynamic packaging.

Encoding jobs are created and controlled using a Job. Each Job contains metadata about the processing to be performed, and contains one or more Tasks that specify a processing task, its input Assets, output Assets, and a media processor and its settings. Tasks within a Job can be chained together, where the output asset of one task is given as the input asset to the next task. By following this approach one Job can contain all of the processing required for a media presentation.

The following diagram shows a high-level overview of the media encoding process used in the Building an On-Demand Video Service with Microsoft Azure Media Services project.

untitled1

The EncodingService class retrieves the asset details from the CMS database and passes the encoding job to Media Services, where it’s submitted to the Azure Media Encoder. The encoding job and video details are saved to the CMS database while the Media Encoder processes the job, retrieving the input asset from Azure Storage, and writing the output assets to Azure Storage. When encoding is complete Media Services notifies the EncodingService class, which generate locator URLS to the output assets in Azure Storage, and updates the encoding job and video details in the CMS database. For a code walkthrough of this process see Encoding process in the Contoso Azure Media Services web service.

By default, each Media Services account can have one active encoding task at a time. However, you can reserve encoding units that allow you to have multiple encoding tasks running concurrently. For more information see How to Scale a Media Service.

Accessing encoded media

Accessing content in Media Services requires a locator, which combines the URL to the media file with a set of time-based access permissions. There are two types of locators – shared access signature (SAS) locators and on-demand origin locators.

A SAS locator grants access rights to a specific media asset through a URL. By using the URL you are granting users who have the URL access to a specific resource for a period of time, in addition to specifying what operations can be performed on the resource.

On-demand origin locators are used when streaming content to a client app, and are exposed by the Media Services Origin Service which pulls the content from Azure Storage and delivers it to the client. An on-demand origin locator URL will point to a streaming manifest file in asset. For more information about the Origin Service see Origin Service.

Summary

This blog post has summarised how to use the Azure Media Encoder to encode uploaded media for delivery to client apps.To do this you create a media processing job that enables you to schedule and automate the encoding of assets. For more info see Building an On-Demand Video Service with Microsoft Azure Media Services.

In my next blog post I’ll discuss the final step in the Media Services workflow – delivering and consuming media.

Friday, 25 July 2014

Using a custom overlay in a Windows Phone QR code scanning app

Previously I’ve demonstrated how to build a simple Windows Phone app to perform QR code scanning, using the ZXing.Net.Mobile library. This library makes the scanning and decoding of bar codes effortless, leaving you to focus on other user experiences in your app.

In this blog post I’m going to extend the sample app so that it doesn’t use the default UI included with ZXing.Net.Mobile, when QR code scanning. Instead, a custom UI will be created and used during the QR code scanning process. This custom UI is referred to as an overlay.

Implementation

The first step is to define the overlay in the XAML code for the page.

<Grid Name="Overlay" Visibility="Collapsed">
    <Grid Background="Transparent">
        <Grid.RowDefinitions>
            <RowDefinition Height="*" />
            <RowDefinition Height="Auto" />
        </Grid.RowDefinitions>
        <Grid.ColumnDefinitions>
            <ColumnDefinition Width="*" />
            <ColumnDefinition Width="*" />
        </Grid.ColumnDefinitions>
        <Button Background="Black" Grid.Row="1" Grid.Column="0" Name="ButtonCancel">Cancel</Button>
        <Button Background="Black" Grid.Row="1" Grid.Column="1" Name="ButtonTorch">Torch</Button>
    </Grid>
</Grid>

This code defines a custom overlay named Overlay, which contains a Cancel button and a Torch button (for toggling on/off the flash) that will appear at the bottom of the page. The next step is pass the overlay to the ZXing.Net.Mobile library.

private UIElement _overlay = null;
 
private async void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    _scanner = new MobileBarcodeScanner(this.Dispatcher);
 
    if (_overlay == null)
    {
        _overlay = this.Overlay.Children[0];
        this.Overlay.Children.RemoveAt(0);
    }
 
    this.ButtonCancel.Click += (s, e2) =>
        {
            _scanner.Cancel();
        };
    this.ButtonTorch.Click += (s, e2) =>
        {
            _scanner.ToggleTorch();
        };
 
    _scanner.CustomOverlay = _overlay;
    _scanner.UseCustomOverlay = true;
 
    var result = await _scanner.Scan();
    ProcessScanResult(result);
}

After creating an instance of the MobileBarcodeScanner class the Overlay is retrieved from the visual tree and stored in a UIElement instance named _overlay. Then, the Cancel and Torch button Click events are wired up to methods in the MobileBarcodeScanner class, to cancel scanning, and toggle the torch respectively. The CustomOverlay property of the MobileBarcodeScanner instance is then set to _overlay, the UseCustomOverlay property of the MoblileBarcodeScanner instance is set to true to indicate that a custom overlay will be used during the QR scanning process, before the Scan method of the MobileBarcodeScanner instance is invoked. The following screenshot shows the custom overlay being displayed during the QR code scanning process (QR code image courtesy of Google Images):

image

While the overlay shown here is basic, it does show the mechanism used for creating a UI for the QR code scanning process that matches the rest of the UI used in your app.

When a QR code is successfully recognized the decoded result can be passed to a method for processing, in this case the ProcessScanResult method. For an explanation of this method see my previous blog post.

Summary

This blog post has demonstrated how to replace the default UI used by ZXing.Net.Mobile, with a custom UI of your own design. This allows you to create a UI for the QR code scanning process that matches the rest of the UI used in your app.

The sample app can be downloaded here.

Thursday, 24 July 2014

QR code scanning in a Windows Phone app

A recent Windows Phone app that I developed had a requirement to include QR code scanning, and to take an action based on the data contained in the QR code. A QR code is a type of machine readable barcode that contains data that can be extracted from patterns present in both horizontal and vertical components of the image. Initially this seemed like quite a big task, but with the help of a library it became an effortless task.

This blog post demos a simple Windows Phone 8 app for performing QR code scanning using ZXing.Net.Mobile. ZXing.Net.Mobile is a .NET library based on the widely used open source ZXing (Zebra Crossing) barcode library, whose goal is to make scanning barcodes as painless as possible in an app.

Implementation

The first step is to add the ZXing.Net.Mobile nuget package to your app, and import the ZXing.Mobile namespace into your class.

private MobileBarcodeScanner _scanner;
 
private async void MainPage_Loaded(object sender, RoutedEventArgs e)
{
    _scanner = new MobileBarcodeScanner(this.Dispatcher);
    _scanner.UseCustomOverlay = false;
    _scanner.TopText = "Hold camera up to QR code";
    _scanner.BottomText = "Camera will automatically scan QR code\r\n\rPress the 'Back' button to cancel";
 
    var result = await _scanner.Scan();
    ProcessScanResult(result);
}

Scanning a QR code is as simple as creating an instance of the MobileBarcodeScanner class, and invoking it’s Scan method. Optional setup includes specifying text to display at the top and bottom of the page, while scanning a QR code, and a flag that indicates whether you want to use ZXings in-built overlay, or specify your own.

The following screenshot shows the app scanning a QR code (courtesy of Google Images).

image

When a QR code is successfully recognized the decoded result can be passed to a method for processing, in this case the ProcessScanResult method. Note that decoding of the image is all automatically performed by the ZXing.Net.Mobile library.

private void ProcessScanResult(ZXing.Result result)
{
    string message = string.Empty;
 
    message = (result != null && !string.IsNullOrEmpty(result.Text)) ? "Found QR code: " + result.Text : "Scanning cancelled";
 
    this.Dispatcher.InvokeAsync(() =>
        {
            MessageBox.Show(message);
        });
}

This method simply extracts the text from the ZXing.Result instance and displays it in a mesage box, as shown in the following screenshot.

image

Obviously in a real app you may choose to log the decoded QR code result somewhere, or in the case of a URL, open it in a web browser.

Summary

This blog post has demonstrated how to construct a simple app for performing QR code scanning, using the ZXing.Net.Mobile library. This library makes the scanning and decoding of bar codes effortless, leaving you to focus on other user experiences in your app.

The sample app can be downloaded here.

Monday, 23 June 2014

Uploading content into Azure Media Services

Previously I’ve introduced the Content Management System (CMS) that’s used to store video details for the video on-demand service, along with details of video encoding jobs. I’ve also explained how to connect to Azure Media Services.

In this blog post I’ll summarise how client apps can upload video to the video on-demand service. For info about the supported codecs and file container formats see Formats Supported by the Media Services Encoder.

Uploading content

To upload content into Media Services you must first create an asset and add files to it, and then upload the asset. This process is known as ingesting content. The content object in Media Services is an IAsset, which is a collection of metadata about a set of media files. Each IAsset contains one or more IAssetFile objects. The approach adopted here is to create an Asset, upload the content to Media Services, and then generate AssetFiles and associate them with the Asset. In order to create an Asset you must first have a reference to the Media Services server context. For more info see Connecting to Azure Media Services.

The following diagram shows a high-level overview of the media upload process used in the Building an On-Demand Video Service with Microsoft Azure Media Services project.

IC721592

The client apps communicate with the web service through a REST web interface. When a new video is uploaded a new asset is created by Media Services, and the asset is uploaded to Azure Storage before the asset details are published to the CMS. The upload process can be decomposed into the following steps:

  1. Create a new empty Asset.
  2. Create an AccessPolicy instance that defines the permissions and duration of access to the Asset.
  3. Create a Locator instance that will provide access to the Asset.
  4. Upload the file that’s associated with the Asset into blob storage.
  5. Publish the Asset.
    • Save the Asset details to the CMS.
    • Generate an AssetFile for the Asset.
    • Add the Asset to the encoding pipeline.

For a code walkthrough of this process see Upload process in the Contoso Azure Media Services applications.

Media Services also allows you to secure your content from the time it leaves your computer, by specifying an encryption option as a parameter when creating an Asset. For more info see Securing media for upload into Azure Media Services.

Summary

This blog post has summarised the media upload process from client apps into a video on-demand service that uses Azure Media Services. For more info see Building an On-Demand Video Service with Microsoft Azure Media Services.

In my next blog post I’ll discuss the next step in the Media Services workflow – encoding and processing uploaded media.