208 lines
8.1 KiB
Markdown
208 lines
8.1 KiB
Markdown
|
# Introduction
|
||
|
|
`<NOTIFICATION>` documents are the basis behind the [NOT](../commands/not.md) and [IPG](../commands/ipg.md) commands.
|
||
|
|
Being such, it was introduced with [MSNP5](../versions/msnp5.md).
|
||
|
|
|
||
|
|
This article only describes the `<NOTIFICATION>` command from .NET Alerts 5.0 and below,
|
||
|
|
and not the `<Notify>` element used in .NET Alerts 6.0 and above.
|
||
|
|
|
||
|
|
# NOTIFICATION
|
||
|
|
This is the root element of the document, and supports four attributes:
|
||
|
|
* `ver`: This is always `1`. Seems optional, or was removed later.
|
||
|
|
* `id`: A 32-bit unsigned integer that is set by the sending party.
|
||
|
|
* `siteid`: The .NET Alerts Site ID, not to be confused with the .NET Passport Site ID.
|
||
|
|
Setting this to some values changes the default icon:
|
||
|
|
* `0`: Use stocks (stack of coins or line-chart) icon
|
||
|
|
* `1`: Use calendar (clock) icon
|
||
|
|
* Other values: Use default bell icon or custom icon
|
||
|
|
* `siteurl`: The base URL to the service used in later relative URL attributes.
|
||
|
|
|
||
|
|
## TO
|
||
|
|
This element supports two attributes:
|
||
|
|
* `pid`: The recipient's Passport Unique ID.
|
||
|
|
The format for the PUID is `0xHHHHHHHH:0xLLLLLLLL`,
|
||
|
|
where `H` is the hexadecimal representation of the profile's `MemberIdHigh` variable,
|
||
|
|
and where `L` is the hexadecimal representation of the profile's `MemberIdLow` variable.
|
||
|
|
* `name`: The recipient's display name or user handle. Optional.
|
||
|
|
|
||
|
|
If this element (`<TO>`) does not have a (`<VIA>`) element, it is to be empty.
|
||
|
|
|
||
|
|
### VIA
|
||
|
|
*NOTE: This element seems to only exist as backwards compatibility from .NET Alerts 6.0.*
|
||
|
|
|
||
|
|
This empty element only supports one attribute:
|
||
|
|
* `agent`: What this alert is intended to be viewed by:
|
||
|
|
* `email`: A e-mail message.
|
||
|
|
* `messenger`: A "toast" generated by the Official Client.
|
||
|
|
* `mobile`: A mobile device.
|
||
|
|
|
||
|
|
## FROM
|
||
|
|
*NOTE: This element should NOT be added to any `<NOTIFICATION>` documents.*
|
||
|
|
|
||
|
|
This optional empty element supports two attributes:
|
||
|
|
* `pid`: The sender's Passport Unique ID. Follows the same format as [`<TO>`](#to)'s `pid` parameter.
|
||
|
|
* `from`: The sender's display name or user handle. Optional.
|
||
|
|
|
||
|
|
## MSG
|
||
|
|
This is the primary element of the document, and supports two attributes:
|
||
|
|
* `pri`: This is always empty, and should NOT be set. May be set to `1` for incoming pages. Optional.
|
||
|
|
* `id`: The notification's numeric ID, defaulting to '0', and should NOT be changed.
|
||
|
|
|
||
|
|
### ACTION
|
||
|
|
This element supports only one attribute:
|
||
|
|
* `url`: The main URL that is used when this notification is activated, relative to `siteurl`.
|
||
|
|
|
||
|
|
When opened by a client, the following are added to the URL as query parameters:
|
||
|
|
* `to_pid`: The `pid` attribute from [`<TO>`](#to) element.
|
||
|
|
* `notification_id`: The `id` attribute from [`<NOTIFICATION>`](#notification) element.
|
||
|
|
* `message_id`: The `id` attribute from [`<MSG>`](#msg) element.
|
||
|
|
* `agent`: The client that activated this notification. The Official Client sets this to `messenger`. Optional.
|
||
|
|
|
||
|
|
### SUBSCR
|
||
|
|
This element supports only one attribute:
|
||
|
|
* `url`: The configuration URL that is used when the notification's `change` option is activated, relative to `siteurl`.
|
||
|
|
|
||
|
|
When opened by a client, the following are added to the URL as query parameters:
|
||
|
|
* `to_pid`: The `pid` attribute from [`<TO>`](#to) element.
|
||
|
|
* `notification_id`: The `id` attribute from [`<NOTIFICATION>`](#notification) element.
|
||
|
|
* `message_id`: The `id` attribute from [`<MSG>`](#msg) element.
|
||
|
|
* `agent`: The client that activated this notification. The Official Client sets this to `messenger`. Optional.
|
||
|
|
|
||
|
|
### CAT
|
||
|
|
*NOTE: This element is obsolete and
|
||
|
|
should NOT be added to any `<NOTIFICATION>` documents.*
|
||
|
|
|
||
|
|
This optional empty element only supports one attribute:
|
||
|
|
* `id`: The category ID of this notification.
|
||
|
|
|
||
|
|
### BODY
|
||
|
|
This is the main body of the document, and supports two attributes:
|
||
|
|
|
||
|
|
* `lang`: The decimal LCID that this notification document is meant to display in. Optional, but should be set.
|
||
|
|
* `icon`: The custom 32x32 PNG icon URL, relative to `siteurl`. Optional.
|
||
|
|
Note: Newer versions of the client support 48x32 icons and will use them automatically
|
||
|
|
if your icon URL has `_32x32` in it, the client can replace it with `_48x32`.
|
||
|
|
If you do not have a 48x32 icon, it will fall-back to the original 32x32 one.
|
||
|
|
|
||
|
|
The default element that this parents is `<TEXT>`. It may also contain other types of data.
|
||
|
|
One such data type is the [`<NotificationData>`](#notificationdata) sub-document.
|
||
|
|
|
||
|
|
This element (including the `<BODY>` and `</BODY>`) are restricted in size to 1024 bytes.
|
||
|
|
|
||
|
|
#### NAME
|
||
|
|
*NOTE: This element should NOT be added to any `<NOTIFICATION>` documents.*
|
||
|
|
|
||
|
|
This optional element contains the friendly name of the recipient.
|
||
|
|
|
||
|
|
#### TEXT
|
||
|
|
This optional element contains the text data of the notification.
|
||
|
|
|
||
|
|
#### TEXTX
|
||
|
|
This optional element contains the extended text data of the notification,
|
||
|
|
supported by [MSNP9](../versions/msnp9.md) and higher.
|
||
|
|
|
||
|
|
The [`<TEXT>`](#text) element is required for this to be parsed by the Official Client.
|
||
|
|
|
||
|
|
The inner docment of this is required to be XML encoded.
|
||
|
|
|
||
|
|
##### P
|
||
|
|
A paragraph, required for [`<TEXTX>`](#textx) elements to parse correctly.
|
||
|
|
|
||
|
|
This element supports one attribute:
|
||
|
|
* `align`: The extended notification's text alignment:
|
||
|
|
* `left`
|
||
|
|
* `center`
|
||
|
|
* `right`
|
||
|
|
|
||
|
|
This element may contain any of the following elements:
|
||
|
|
* `P`: Nested paragraph, also supporting the `align` element.
|
||
|
|
* `B`: Bold text.
|
||
|
|
* `I`: Italic text.
|
||
|
|
* `BR`: This empty element denotes a line-break.
|
||
|
|
|
||
|
|
# NotificationData
|
||
|
|
This element may instead be contained in the [`<BODY>`](#body) element entirely,
|
||
|
|
replacing all of it's children.
|
||
|
|
This sub-document is XML encoded if set as the inner data of the [`<BODY>`](#body) element.
|
||
|
|
|
||
|
|
This element supports two attributes:
|
||
|
|
* `xmlns:xsd`: is always set to `http://www.w3.org/2001/XMLSchema`
|
||
|
|
* `xmlns:xsi`: is always set to `http://www.w3.org/2001/XMLSchema-instance`
|
||
|
|
|
||
|
|
## Service
|
||
|
|
Contains only `ABCHInternal`. Unknown if there are other values supported.
|
||
|
|
|
||
|
|
This element is exclusive to notifications generated by the [Address Book Service](../services/abservice.md).
|
||
|
|
|
||
|
|
## CID
|
||
|
|
Contains only the Contact ID of the user associated with this notification.
|
||
|
|
|
||
|
|
This element is exclusive to notifications generated by the [Address Book Service](../services/abservice.md).
|
||
|
|
|
||
|
|
## SpaceHandle
|
||
|
|
This element only has one child named `ResourceID`.
|
||
|
|
|
||
|
|
This element and it's children are exclusive to notifications generated by the blog service.
|
||
|
|
|
||
|
|
### ResourceID
|
||
|
|
Contains the blog service's ID for this user.
|
||
|
|
|
||
|
|
## ComponentHandle
|
||
|
|
This element only has one child named `ResourceID`.
|
||
|
|
|
||
|
|
This element and it's children are exclusive to notifications generated by the blog service.
|
||
|
|
|
||
|
|
### ResourceID
|
||
|
|
Contains the blog service's ID for the main component.
|
||
|
|
|
||
|
|
## OwnerCID
|
||
|
|
This element only contains a signed 64-bit integer for the Contact ID.
|
||
|
|
Added since [MSNP13](../versions/msnp13.md).
|
||
|
|
|
||
|
|
This element and it's children are exclusive to notifications generated by the blog service.
|
||
|
|
|
||
|
|
## LastModifiedDate
|
||
|
|
Contains a ISO 8601-compatible timestamp with 7 millisecond digits.
|
||
|
|
|
||
|
|
This element is omitted in notifications generated by the persistant group service.
|
||
|
|
|
||
|
|
## Action
|
||
|
|
Only observed to contain `Add`. Unknown if there are other values supported.
|
||
|
|
|
||
|
|
This element is exclusive to notifications generated by the blog service.
|
||
|
|
|
||
|
|
## HasNewItem
|
||
|
|
Contains either `true` or `false`.
|
||
|
|
|
||
|
|
## ComponentSummary
|
||
|
|
This element has two children named `<Component>` and `<Items>`.
|
||
|
|
|
||
|
|
This element and it's children are exclusive to notifications generated by the blog service.
|
||
|
|
|
||
|
|
### Component
|
||
|
|
This element has one child named `ResourceID` and supports one attribute:
|
||
|
|
* `xsi:type`: The type of this `<Component>`:
|
||
|
|
* `List`: A list.
|
||
|
|
* `Folder`: A photo collection.
|
||
|
|
* `MessageContainer`: A text message container.
|
||
|
|
|
||
|
|
#### ResourceID
|
||
|
|
Contains the blog service's ID for this `<Component>`.
|
||
|
|
|
||
|
|
### Items
|
||
|
|
This element supports multiple `<Item>` child elements.
|
||
|
|
|
||
|
|
#### Item
|
||
|
|
This element has one child named `ResourceID` and supports one attribute:
|
||
|
|
* `xsi:type`: The type of this `<Component>`:
|
||
|
|
* `ListEntry`: An entry on a list.
|
||
|
|
* `Photo`: A photo.
|
||
|
|
* `Message`: A text message.
|
||
|
|
|
||
|
|
##### ResourceID
|
||
|
|
Contains the blog service's ID for this `<Item>`.
|
||
|
|
|
||
|
|
## CircleId
|
||
|
|
Contains the GUID of the persistant group.
|
||
|
|
|
||
|
|
This element is exclusive to notifications generated by the persistant group service.
|