====== onSIPPresence() ======
wrtc.onSIPPresence() is an event function called when the presence status of a person you are [[ixnx:wrtc:js:api:wrtc:setsipsubscribe|subscribing to]] is changed.

You can use this event to update user's status on screen.

===== Occurs =====
A SIP presence update has been received from SIP presence server.

===== Arguments =====
wrtc.onSIPPresence(arg)
  * arg - JSON structure containing received SIP presence information

The contents of the JSON structure can differ depending on the type of information received:

==== Presence ====
Usually the received presence information has the following format: \\
{type:"sip_presence_notify", from:..., basic:..., activity:..., note:..., format:"application/pidf+xml", subscription_state:..., msg:...}
  * fromAdress - string containing SIP address of person who's state has changed
  * available - boolean, true if person is available
  * activity - (optional) string containing activity description according to [[https://tools.ietf.org/html/rfc4480#section-3.2|RFC4480 section 3.2]]
  * note - (optional) string containing free text description
  * subscription_state - (optional) string containing subscription state, eg "active;expires=296" (seconds)
  * msg - string containing the SIP presence message as it was received from server
Usually you do not need to examine all arguments to be able to display correct presence information. Basic "available yes/no" information is given in arg.available. More detailed information can be found in arg.activity and arg.note. There is rarely need to examine the other arguments.

==== Subscribers ====
If you have [[ixnx:wrtc:js:api:wrtc:setsipsubscribe|subscribed]] to your own status you do not get the above response, but a list of who are subscribing to your presence status: \\
{type:"sip_presence_notify", from:..., format:"application/watcherinfo+xml", msg:...}
  * from - string containing your SIP address
  * msg - string containing the SIP presence message as it was received from server
You need to parse the raw SIP message yourself to extract the list of persons subscribing to your presence status.

==== Error ====
If you have called [[ixnx:wrtc:js:api:wrtc:setsipsubscribe|wrtc.setSIPSubscribe()]] or [[ixnx:wrtc:js:api:wrtc:setsippresence|wrtc.setSIPPresence()]] but an error has occurred the argument JSON structure will contain: \\
{type:..., from:..., error:..., msg:...}
  * type - string describing error origin:
    * "sip_presence_subscribe" - [[ixnx:wrtc:js:api:wrtc:setsipsubscribe|wrtc.setSIPSubscribe()]]
    * "sip_presence_publish" - [[ixnx:wrtc:js:api:wrtc:setsippresence|wrtc.setSIPPresence()]] 
  * from - string containing SIP address of error origin
  * error - error number:
    * 404 - could not send presence publish or presence subscribe SIP message
    * other error numbers may also occur
  * msg - string error description in English

===== Return value =====
Ignored.

===== Eample =====
<code>
{type:"sip_presence_notify", fromAdress:"john.doe@company.com", available:true, note:"Available", format:"application/pidf+xml", subscription_state:"active;expires=296", msg:"<?xml version='1.0' encoding='UTF-8'?><presence xmlns='urn:ietf:params:xml:ns:pidf' xmlns:dm='urn:ietf:params:xml:ns:pidf:data-model' xmlns:rpid='urn:ietf:params:xml:ns:pidf:rpid' xmlns:c='urn:ietf:params:xml:ns:pidf:cipid' xmlns:lt='urn:ietf:params:xml:ns:location-type' entity='sip:john.doe@company.com'><tuple id='t1120a64d'><status><basic>open<\/basic><\/status><\/tuple><dm:person id='pa920ee13'><dm:note>Available<\/dm:note><\/dm:person><\/presence>"}
</code>

<code>
wrtc.onSIPPresence = function(arg) {
    if (arg.error)
        window.alert(arg.fromAdress + ": error " + arg.error + ": " + arg.msg);
    else if (arg.format == "application/watcherinfo+xml")
        -- update list of persons subscribing to your presence --
    else
        -- update list of presence with arg.activity and arg.note --
}
</code>

===== See also =====
[[ixnx:wrtc:js:api:wrtc:setsipsubscribe|wrtc.setSIPSubscribe()]]

[[ixnx:wrtc:js:api:wrtc:setsippresence|wrtc.setSIPPresence()]]