Work with command parameters

It is not unusual for service-side command handlers to require parameters that must be provided by the client. For example, a function to load files would need to know which files the user wants to load. To convey this sort of information to the service, you would include it as additional parameters in the command request sent from the client, as described in this section.

The reverse is also true: clients may need response parameters back from the service. For example, if a client sends a command to perform a search, it will expect to receive the search results in the response. In this section, we describe how to write to the response object, so that the client can use this data in command callbacks.

How-to

Set command parameters from the client

APIs:

WebClient.queueCommand() | HTML5 | Android
PWWebClient.queueCommand() | iOS

To send command-specific parameters to the service from the client, you provide them as the second argument of the queueCommand call. The parameters are expressed as an array of key-value strings (the service can convert the values to different data types, as explained further down).

The syntax will look something like this:

HTML5

pureweb.getClient().queueCommand('NiftyCommand', {'Key1': 'Value1', 'Key2': 'Value2'});

iOS (Obj-C)

NSDictionary *params = @{@"Key1",@"Value1",@"Key2",@"Value2"};
[[PWFramework sharedInstance].client queueCommand:@"NiftyCommand" withParameters:params];

Android

Map<String, Object> parameters = new HashMap<String, Object>();
parameters.put("Key1", "Value1");
parameters.put("Key2", "Value2");
framework.getWebClient().queueCommand("NiftyCommand", parameters);

This adds the parameters to the command object, an XML object generated and maintained under the hood by the StateManagerServer class.


Get command parameters from the service

On the service, the command handler takes the command XML object in its arguments, which enables it to access the parameters passed from the client.

The parameters are stored as strings, and you may need to convert them to different types on the service before you can use them. The snippets below show how to convert a parameter to an integer.

The syntax for getting the parameters varies for each programming language, as illustrated in the snippets below.

C++

void MyApp::MyCommandHandler(Guid sessionId, Typeless command, Typeless responses)
{
	// Getting the first key-value pair from the client-side command, where the value is a string
	String commandHandlerVariable1_key = command["key1"];
	String commandHandlerVariable1_value = command["value1"];
	
	// Getting the second key-value pair from the client-side command, where the value is converted to an integer
	String commandHandlerVariable2_key = command["key2"];
	int commandHandlerVariable2_value = command["value2"].As<int>();
    }
}

You may also be interested in how to convert a PureWeb string to a standard string in C++.

.Net

private void MyCommandHanlder(Guid sessionId, XElement command, XElement responses)
{
    // Getting the first key-value pair from the client-side command, where the value is a string
    var commandHandlerVariable1_key = command.GetText("/key1");
    var commandHandlerVariable1_value = command.GetText("/value1");

    // Getting the second key-value pair from the client-side command, where the value is converted to an integer
    var commandHandlerVariable2_key = command.GetText("/key2");
    var commandHandlerVariable2_value = command.GetTextAs<int>("/value2");
}

Java

private class MyCommandHandler implements CommandHandler
{
    public void invoke(UUID sessionId, Element command, Element responses)
    {
        // Getting the first key-value pair from the client-side command, where the value is a string
        String commandHandlerVariable1_key = XmlUtility.getText(command, "/key1");
        String commandHandlerVariable1_value = XmlUtility.getText(command, "/value1");

        // Getting the second key-value pair from the client-side command, where the value is converted to an integer
        String commandHandlerVariable2_key = XmlUtility.getText(command, "/key1");
        Int commandHandlerVariable2_value = XmlUtility.getTextAs(Integer.class, command, "/value2");
    }
}


Set response parameters from the service

If the service application needs to send a command response to the client, it can do so by writing key-value pairs to the responses XML object. This is done from within the command handler.

Because command parameters and responses are all transmitted as strings, if you want to send binary data, you must first encode it as a Base64 string.

Like the command object, the responses XML object is automatically generated and maintained under the hood by the StateManagerServer class. It is included in the command handler's arguments, enabling the handler to write to it.

C++

void MyApp::MyCommandHandler(Guid sessionId, Typeless command, Typeless& responses)
{
    responses["ResponseKey1"] = "ResponseValue1";
    responses["ResponseKey2"] = "ResponseValue2";
}

.Net

void MyCommandHandler(Guid sessionId, XElement command, XElement responses)
{
    responses.Add(new XElement("ResponseKey1", "ResponseValue1"));
    responses.Add(new XElement("ResponseKey2", "ResponseValue2"));
}

Java

private class MyCommandHandler implements CommandHandler
    public void invoke(UUID sessionID, Element command, Element responses)
    {
        responses.addContent(new Element("ResponseKey1", "ResponseValue1"));
        responses.addContent(new Element("ResponseKey2", "ResponseValue2"));
    }

The response parameters will be encapsulated in the client-side CommandResponseEventArgs object, which is passed as argument to the command callback.