Show 

Home > Event Handler

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.

POST

URL:  /eventhandlers?appid=[appid]

Action

Create an eventhandler.

Request XML Payload

<web_service version="1.0">
 <eventhandler>
    <eventsubscribe action="add"
      type="any" resource_id="any"
      resource_type="any"/>
 </eventhandler>
</web_service>

HTTP Return Code

Success: 201 CREATED

Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR

Response XML Payload

<web_service version="1.0">
  <eventhandler_response identifier="e686876c-e446-4be7-9b70-
    beb3059b5fc9" appid="app"
    href="http://192.168.1.140:81/default/eventhandlers/e686876c-
     e446-4be7-9b70-beb3059b5fc9">
    <eventsubscribe type="any" resource_id="any"
    resource_type="any"/>
  </eventhandler_response>

PUT

URL:  /eventhandlers/[eventhandler_id]?appid=[appid]

Action

Update/change an eventhandler subscription.

Request XML Payload

<web_service version="1.0">
 <eventhandler>
    <eventsubscribe action="add"
     type="end_play" />
 </eventhandler>
</web_service>

HTTP Return Code

Success: 200 OK

Error: 404 NOT FOUND or 500 INTERNAL SERVER ERROR

Response XML Payload

<web_service version="1.0">
  <eventhandler_response identifier="e686876c-e446-4be7-9b70-
    beb3059b5fc9" appid="app"
    href="http://192.168.1.140:81/default/eventhandlers/e686876c-e446-
     4be7-9b70-beb3059b5fc9">
    <eventsubscribe type="any" resource_id="any" resource_type="any"/>
    <eventsubscribe type="end_play" resource_id="any"
    resource_type="any"/>
  </eventhandler_response>
</web_service>

DELETE

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

GET

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"?>
<web_service version="1.0">
   <eventhandlers_response size="2">
   <eventhandler_response appid="app"
    href="http://192.168.1.140:81/default/eventhandlers/1d355db5-9443-
      4d8a-a7c5-3843ca883e19" identifier="1d355db5-9443-4d8a-a7c5-
      3843ca883e19">
      <eventsubscribe resource_id="any" resource_type="any" type="any"/>
   </eventhandler_response>
   <eventhandler_response appid="app"
     href="http://192.168.1.140:81/default/eventhandlers/55b91492-5645-
       4e23-b4b8-dbf5ffadb168" identifier="55b91492-5645-4e23-b4b8-
       dbf5ffadb168">
   <eventsubscribe resource_id="any" resource_type="any" type="any"/>
   </eventhandler_response>
</eventhandlers_response>

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">
  <eventhandler_response appid="app"
    href="http://192.168.1.140:81/default/eventhandlers/1d355db5-
      9443-4d8a-a7c5-3843ca883e19" identifier="1d355db5-9443-4d8a-
      a7c5-3843ca883e19">
   <eventsubscribe resource_id="any" resource_type="any"
   type="any"/>
  </eventhandler_response>
<web_service version="1.0">

XML Schema Definition for Event Handler

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>

<eventhandler> Element Attribute

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

<eventsubscribe> Parameters

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

<eventhandler_response> Parameters

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.

Event Handler Scenario

This diagram of an eventhandler scenario illustrates how to create and monitor events.