Home > Event Handler
HTTP event streaming is implemented in the PowerMedia XMS RESTful server as an eventhandler resource. When the client wishes to receive asynchronous events, it uses the web service to create an eventhandler and to subscribe to specific event types.
For example, when the client performs an HTTP GET on a newly created eventhandler, the PowerMedia XMS RESTful server responds with a 200 OK; however, the TCP connection remains open until the client destroys the eventhandler. Event data related to resources and subscribed event types are sent to the client until it deletes the eventhandler.
The following tables show the HTTP methods that can be used with the eventhandler.
Note: The payloads shown are examples only as there are many possible variations.
URL: /eventhandlers?appid=[appid] |
|
Action | Create an eventhandler. |
Request XML Payload |
<web_service version="1.0"> |
HTTP Return Code |
Success: 201 CREATED Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR |
Response XML Payload |
<web_service version="1.0"> |
URL: /eventhandlers/[eventhandler_id]?appid=[appid] |
|
Action | Update/change an eventhandler subscription. |
Request XML Payload |
<web_service version="1.0"> |
HTTP Return Code |
Success: 200 OK Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR |
Response XML Payload |
<web_service version="1.0"> |
URL: /eventhandlers/[eventhandler_id]?appid=[appid] |
|
Action |
Delete an eventhandler. |
Request XML Payload |
N/A |
HTTP Return Code |
Success: 204 NO CONTENT Error: 404 NOT FOUND |
Response XML Payload |
N/A |
The GET method has two options – one gets all eventhandlers and the other gets one eventhandler specified by the [eventhandler_id].
URL: /eventhandlers?appid=[appid] |
|
Action | Get all eventhandlers. |
Request XML Payload |
N/A |
HTTP Return Code |
Success: 200 OK Error: 404 NOT FOUND |
Response XML Payload |
<?xml version="1.0" encoding="UTF-8" standalone="no"?> |
URL: /eventhandlers/[eventhandler_id]?appid=[appid] | |
Action |
Get an eventhandler. |
Request XML Payload |
N/A |
HTTP Return Code |
Success: 200 OK Error: 404 NOT FOUND |
Response XML Payload |
<web_service version="1.0"> |
The following XML schema definitions provide a formal definition of all possible XML payloads that are valid with the eventhandler element.
eventsubscribe
<xs:element name="eventsubscribe">
<xs:complexType>
<xs:attribute name="type" type="event_type" default="any" />
<xs:attribute name="action" type="action_option" default="add" />
<xs:attribute name="resource_id" type="xs:string" default="any" />
<xs:attribute name="resource_type" type="event_resource_type" default="any" />
</xs:complexType>
</xs:element>
request payload
<<xs:element name="eventhandler">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventsubscribe" minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
</xs:complexType>
</xs:element>
single instance response payload
<xs:element name="eventhandler_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventsubscribe" minOccurs="1" maxOccurs="unbounded" />
</xs:sequence>
<xs:attributeGroup ref="response_attrgroup" />
</xs:complexType>
</xs:element>
get all instances response payload
<xs:element name="eventhandlers_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="eventhandler_response" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="size" type="xs:string" use="required" />
</xs:complexType>
</xs:element>
The following table lists all valid parameters, their definitions and their valid and default values that can be used in an XML payload for an eventhandler. The HTTP method(s) in which they can be used is also provided.
Attribute |
Description |
HTTP Method |
eventsubscribe |
Refer to the <eventsubscribe> parameters. |
POST/PUT |
The following table lists all valid parameters, their definitions and their valid and default values that can be used in an XML payload as part of an eventhandler.
Parameter |
Description |
Values |
type |
Type of events to monitor. |
end_play end_playcollect end_playrecord end_overlay incoming ringing connected hangup dtmf cpa tone keepalive any (default) |
resource_type |
Monitor events for a specific resource type. |
call conference any (default) |
resource_id |
Monitor events for a specific resource. |
N/A |
action |
Add/remove the subscription. |
add (default) remove |
The following table lists all valid parameters, their definitions and valid values that can be returned by XMS in an XML payload as part of the response to an eventhandler POST or PUT.
Parameter |
Description |
identifier |
A unique ID of an eventhandler resource. |
href |
http: address of an eventhandler resource. |
appid |
Unique application ID included in the original HTTP POST creation process that is utilized by the web service such that clients only have access to resources that they created. |
eventsubscribe |
Refer to the <eventsubscribe> attributes. |
size |
Number of eventhandlers. |
This diagram of an eventhandler scenario illustrates how to create and monitor events.