Send custom parameters with an image

Sometimes, it can be useful to pass custom parameters along with the image streamed from the service. This could be any arbitrary metadata that your application cares to know about the image, such as a date, geographic coordinates, a description, and so on.

Steps

Populate parameters on the service

APIs:

RenderTarget | C++ | .Net | Java

On the service, in the implementation of RenderTarget, the target exposes a parameter map to which you can add values. Like other instances of parameters maps in PureWeb, these are expressed as an array of key-value strings. You can convert the parameters to different data types when you retrieve them from the client.

C++

CSI::Collections::Map<String,String> MyCustomParameters = target.Parameters();
MyCustomParameters["MyCustomKey"] = "MyCustomValue";

.Net

target.Parameters["MyCustomKey"] = "MyCustomValue";

Java

Map<String,String> myCustomParameters = target.getParameters();
myCustomParameters.put("MyCustomKey", "MyCustomValue");


Retrieve parameters from the client

APIs:

ViewUpdatedEventArgs | HTML5 | Android
PWViewUpdatedEventArgs | iOS

On the client, to access custom image parameters, listen for the ViewUpdated event on the view. The parameters are exposed as a property on the ViewUpdatedEventArgs object.

This object provides a getEncodingParameters method, which you can use to retrieve the parameters.

  The ViewUpdatedEventArgs object contains all the parameters that the frame was encoded with, including any parameter passed as argument to the EncoderFormat (see Add custom encoding parameters).

HTML5

pureweb.listen(mainView, pureweb.client.View.EventType.VIEW_UPDATED,
function(e){
    var CustomParametersFromService = e.getEncodingParameters();
    var CustomKey = CustomParametersFromService["MyCustomValue"]; 
});

iOS (Obj-C)

- (void)viewWasUpdated:(PWViewUpdatedEventArgs *)args
{
    NSString* customValue = [args.encodingParameters objectForKey:@"customKey"];
    ...
}

Android

view.addViewUpdatedHandler(new OnViewUpdated());

private class OnViewUpdated implements EventHandler<ViewUpdatedEventArgs> {
    public void invoke(Object source, ViewUpdatedEventArgs args) {
        Map<String, String> customParametersFromService = args.getEncodingParameters();
        String customKey = customParametersFromService.get("MyCustomValue");
    }
}