Calling Interface Methods

The callMethod method signature is defined as follows:

callMethod: function(
  callMethodSuccess, //Callback on success function
  callMethodError, //Callback on error function
  destination, //TODO: Determine what this does
  path, //TODO: Determine what this does
  indexList, //Points to the interface method definition
  inParameterType, //A string representing the input parameter types
  parameters, //The input parameters (does not include the out parameters)
  outParameterType //A string representing the output types
)

Sample usage:

//The interface method being called looks like this:
//'?TransitionLampState Timestamp<t NewState<a{sv} TransitionPeriod<u LampResponseCode>u

app.lightbulbSession.callMethod(
  callMethodSuccess, //See below for a description.
  callMethodError, 
  null, 
  null, 
  [2,0,4,0], //(the proxy object list, the first object within the proxy object list, the fourth    interface for that object, and the first method defined by that interface (See Index List Description).
  'ta{sv}u', //(in parameter types) unsigned-long, map of type (string, variant), unsigned-integer 
  inputParameters, //The input parameters (does not include the out parameter; must match above type signature)
  'u' //(out parameter type) unsigned-integer 
);

Descriptions of the parameters which seem the most non-obvious are given below.

callMethodSuccess

The first parameter is the on-success callback function. Perhaps the only non-obvious thing to note is that the out parameters are passed to this function as an array of arguments. Using the above example, the first parameter might be defined as follows:

var callMethodSuccess = function(outParameters) {
  var lampResponseCode = outParameters[0]; //We know this is an unsigned-integer because we passed a 'u' as the outParameterType.
  //Do something with response code...
}

destination

Based on the examples, the third parameter (destination) is typically either null (as in the lighting sample), or is set to the session host (as in the tv sample). Specifics of this parameter are under investigation.

path

Based on the examples, null is always passed for this parameter (still under investigation).

inParameterType

The 6th parameter (inParameterType) specifies the type signature for the input parameters. It has somewhat of a confusing format; essentially take the type codes for each of the interface's input parameters and concatenate them together. Using the above example, we have the types 't' (unsigned-long), 'a{sv}', and 'u' respectively for the input parameters. So, the inParameterType would be 'ta{sv}u'.

parameters

The 7th parameter (inputParameters) specifies the array of arguments that will be passed to the interface method. This is fairly straight-forward, just make sure that the arguments ordered as per the interface definition and are of the correct type. For the above example, the inputParameters could be as follows:

var inputParameters =
  [
    123456, //Timestamp<t
      [ 
        ['OnOff', 'b', true],
        ['Hue', 'u', 37],
        ['Saturation', 'u', 48],
        ['ColorTemp', 'u', 9],
        ['Brightness', 'u', 51]
      ], //NewState<a{sv}
    4 //TransitionPeriod<u
  ];

outParameterType

The 8th parameter (outParameterType) follows the same format as the inputParameterType. Just take the type signatures for all of the output parameters of the interface method and concatenate them together. The above example contains one out parameter with type code 'u' (LampResponseCode>u), so the outParameterType is just 'u'.