Web API Parameter

====== Handle ======

"Handle" is the general term for something which is stored. There are handles for every item: for playbacks, palettes, workspaces, groups, fixtures and more. To get an impression what handles are in your show you might use [[webapi:examples:titanids]].

With regards to the Web API there are three ways to identify a handle:
  * by usernumber - this is the number you set using ''Set Legend'' in Titan. In order to use this method denote the handle as \\ ''handle_userNumber=2''
  * by location - this is the 'place' where you find this item in the Titan UI, e.g. the 6th button on page 1 in the Fixtures and Playbackswindow. In order to use this method identify the handle as \\ ''handle_location=Presets_1_6''
    * 'Presets' is the handle group i.e. the workspace window "Fixtures and Playbacks". See [[macros:identifier:location|]] for the available groups
    * 1 is the page number (1-based)
    * 6 is the button number on that page (1-based)
    * all three parts are concatenated wih underscores ''_''. [[webapi:examples:titanids]] already gives the correct location string.
  * by Titan ID. Everything in the show has a unique ID which is set by the system and cannot be changed by the user. You can get the Titan IDs of your show with [[webapi:examples:titanids]]. There are some useful reserved IDs for masters, see [[macros:identifier:titanid|]]. In order to use this method to identify a handle the notation is \\ ''handle_titanId=2335''.

==== Example ====

Let's assume we want to kill a particular cuelist using [[webapi:requests:playbacks_killplayback]]. The prototype for this is

  http://[ip]:4430/titan/script/2/Playbacks/KillPlayback?handle={handle}

Given a show where a cuelist is recorded in the Fixtures and Playbacks window (group: Presets), page 1, button 6, and this cuelist (here: Cue List 2) has the user number 2:

{{:webapi:requests:killplayback.png|}}

Luckily [[webapi:examples:titanids]] already shows the Titan ID and the correct location (it's the "Computed Web API Location string"). 

{{:webapi:requests:killplayback_2.png|}}

We can kill this cuelist by one of the following ways:

''%%http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_userNumber=2%%'' - by user number
''%%http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_location=Presets_1_6%%'' - by location
''%%http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId=2335%%'' - by titan Id

It appears that Titan applies some guessing and interprets the handle as userNumber if no other type is defined. Hence, 

''%% http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle=2 %%'' does also work. 

==== Errors ====

Various errors may result from wrong or incomplete parameters:

''%%http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle=Presets_1_6%%'' does not work and throws the error \\ ''"Error: Failed to parse value to AcwUserNumber"''

Reason: the part ''_location'' is missing, thus Titan tries to parse this as usernumber (default), and fails.

----

''%%http://localhost:4430/titan/script/2/Playbacks/KillPlayback?2%%'' does not work and results in \\ ''"Error: Der Objektverweis wurde nicht auf eine Objektinstanz festgelegt."'' (no object referenced)

Reason: the parameter name and parsing (handle_userNumber) and the equal sign is missing.

----

''%%http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId=23350%%'' leads to \\ ''"Error: Unable not find handle in group 'playbackHandle' with index '23350'.\r\nParametername: handle"'' 

Reason: the specified handle could not be found (there doesn't exist a handle in that location/with that titanId)

----

''%%http://localhost:4430/titan/script/2/Playbacks/KillPlayback?%%'' throws \\ 
''"Error: Die Sequenz enthält kein übereinstimmendes Element."'' (no matching element in sequence) 

Reason: the handle wasn't correctly specified or not specified at all

----

''%%http://localhost:4430/titan/script/2/Playbacks/KillPlayback?handle_titanId=%%'' gives \\ ''"Error: Die Eingabezeichenfolge hat das falsche Format."'' (wrong format)

Reason: the parameter name and parsing was correctly set but no value given.

==== Used In ====

{{backlinks>.}}