<h2>HTTP request</h2>

<p>To send a start or stop signal, a simple HTTP GET request must be sent to the TIM Enterprise web server.</p>
<p>Every request to the web server requires authentication, so ensure that the relevant HTTP authentication headers are sent with your request and that the username and password combination match an existing <b>web user</b> object in the Directory.</p>

<p>The response status code will indicate success or failure.</p>

<h2>Request format</h2>

<p>The request should be a GET request and take the following URL-encoded parameters, as per the following example:-</p>

http://192.168.0.1/signal.js?cat=4&type=1&objtype....

<p>Valid parameters are described in the table below:-</p>

<table class="confluenceTable">
	<tbody>
		<tr>
			<th class="confluenceTh" width=100>Parameter</th>
			<th class="confluenceTh">Description</th>
		</tr>
		<tr>
			<td class="confluenceTd"><span class="keyword">cat</span></td>
			<td class="confluenceTd">Signal category. For audio masking, this value is always <span class="keyword">0x04</span></td>
		</tr>
		<tr>
    		<td class="confluenceTd"><span class="keyword">type</span></td>
   			<td class="confluenceTd">
        		The type of signal. Valid values for <span class="keyword">0x04-category</span> signals are:-
        		<ul class="table">
       				<li><span class="keyword">0x01 Mute On</span></li>
        			<li><span class="keyword">0x02 Mute Off</span></li>
        		</ul>
    		</td>
		</tr>
		<tr>
    		<td class="confluenceTd"><span class="keyword">objtype</span></td>
    		<td class="confluenceTd">
        		The type of object that this signal relates to. This can be one of two values:-
        		<ul class="table">
        			<li><span class="keyword">user</span> (a user object)</li>
        			<li><span class="keyword">channel</span> (a channel object)</li>
        		</ul>
    		</td>
		</tr>
		<tr>
    		<td class="confluenceTd"><span class="keyword">objid</span></td>
    		<td class="confluenceTd">
        		The unique ID of the object type as specified by the <span class="keyword">objtype</span> parameter (above). This is used to locate the object in the Directory.
        		<p>The region of the Directory to search in is specified by the <span class="keyword">key</span> parameter (below) and governed by the access implied by the placement of the web user 
				whose credentials are used to effect the web request.</p>
    		</td>
		</tr>
		<tr>
    		<td class="confluenceTd"><span class="keyword">key</span></td>
    		<td class="confluenceTd">
        		Specifies the key relating to a container object in the directory (or blank, implying the whole directory) whereby a search on the object specified by 
				<span class="keyword">objtype</span> and <span class="keyword">objid</span> is performed below.
    		</td>
		</tr>
	</tbody>
</table>

<p>Return values are specified as HTTP response status code. Although the body of some responses may contain informational text, you should not rely on this text to make any decisions as to whether the request was successful or not.</p>

<p>Valid status codes are as follows:-</p>

<table class="confluenceTable">
	<tbody>
		<tr>
			<th class="confluenceTh" width=100>Parameter</th>
			<th class="confluenceTh">Description</th>
		</tr>
		<tr>
			<td class="confluenceTd"><span class="keyword">200</span></td>
			<td class="confluenceTd">The signal was received and stored successfully.</td>
		</tr>
		<tr>
    		<td class="confluenceTd"><span class="keyword">400</span></td>
   			<td class="confluenceTd">
        		The request was not acceptable for one of the following reasons:-
        		<ul class="table">
            		<li>An invalid <span class="keyword">type</span> parameter was specified. The <span class="keyword">type</span> parameter is specific to the category specified by the <span class="keyword">cat</span> parameter. 
						Further, the <span class="keyword">type</span> value (e.g. 0x01) can be used in multiple categories.
					</li>
            		<li>The <span class="keyword">objid</span> was missing. Specify the ID of the object you want the signal to relate to.</li>
            		<li>The <span class="keyword">cat</span> and <span class="keyword">type</span> parameters (category and signal type, respectively) must be specified and cannot be zero.</li>
            		<li>The version of TIM Enterprise you are running does not understand the <span class="keyword">signal.js</span> script.</li>
        		</ul>
    		</td>
		</tr>
		<tr>
    		<td class="confluenceTd"><span class="keyword">404</span></td>
    		<td class="confluenceTd">The object specified by the combination of the <span class="keyword">objtype</span> and <span class="keyword">objid</span> parameters 
				(and optionally the <span class="keyword">key</span> parameter) could not be found.
			</td>
		</tr>
		<tr>
    		<td class="confluenceTd"><span class="keyword">500</span></td>
    		<td class="confluenceTd"><b>Internal Server Error</b> prevented the signal from being stored successfully. This may be due to a badly-configured database, or the 
				lack of a signals table in the TIM Enterprise database.
			</td>
		</tr>
	</tbody>
</table>