Using Oxide Web - fullphat/snarl_network_protocol GitHub Wiki

This is provisional documentation. Applications should not attempt to implement any features listed in this document, other than for development or testing purposes. The documentation is provided for open access to encourage interest in forthcoming features and to solicit feedback and suggestions. It is therefore provided "as is" and is subject to ongoing change and revision.

Applications

Registering

To register, POST to the registrations service specifying the identifier of the application you want to register, as follows:

POST /v2/registrations/{AppId}

A completed RegistrationContent object should be included in the request. A suitable password should also be included in the request Oxide-Password header.

Deleting a registration

To delete a registration, send a DELETE request to the registrations service as follows:

DELETE /v2/registrations/{AppId}

Note, however, that this completely removes the application's registration with Snarl, including any customisation the user may have performed. Programmatically removing an application's registration may also be blocked by user or administrative settings in force. Typically, removing a registration would only be done as part of an application's uninstallation process.

Events

Creating or Updating Events

Notifications

Displaying a Notification

Notifications are displayed by POSTing a completed NotificationContent object to the \notifications service. The service accepts three optional parameters, as follows:

POST /v2/notifications/[{AppId}[/{EventId}[/{Uid}]]]

AppId and EventId identify the application and event class to use; Uid specifies a unique identifier to use for the notification. An EventId cannot be specified without an AppId and, similarly, a Uid requires both an EventId and AppId to be included.

Specifying a Uid allows the notification to be subsequently updated or removed by the application. Conversely, not specifying an application, event or unique identifier may prevent the notification from being displayed depending on how the end user has configured Snarl.

Generating a notification using only the service root should only be used for testing purposes.

Only one notification per event class can be displayed on screen at any one time; subsequent notifications within the same event class will cause the existing notification to be changed indicating other notifications have been generated, as follows:

The first notification is displayed, however it is subsequently followed by another notification from the same application and event class. This causes the first notification to be replaced with the second.

Updating a Notification

An existing notification can be updated so long as it was created with a Uid. To update a notification, POST a NotificationContent object with the required changes to the /notifications service, for example:

POST /v2/notifications/elliot/lanman/cs30

{
  "title": "Creating rainbow tables...",
  "text": "Target is 'cs30.ecorp.net'"
}

Creates a notification with a unique identifier of cs30. If we now follow up with:

POST /v2/notifications/elliot/lanman/cs30

{
  "title": "Exploit succeeded!",
  "text": "cs30.ecorp.net is now pwned..."
}

The existing notification is updated to look like this:

Items passed as Null will be ignored, however items set to "" (an empty string) will cause that item to be cleared.

Replacing a Notification

Similar to updating a notification, but include UidToReplace in the new NotificationContent object. This will remove the existing notification; then display the new one.

Specifying Icons

You can specify the icon to use in NotificationContent->Icon, or by setting specific NotificationContent->Icons entries.

Avoid setting both NotificationContent->Icon and NotificationContent->Icons entries as this can have unpredictable results.

Using NotificationContent->Icon remains the simplest way to specify an icon, and has the added benefit that Snarl will decode the icon type provided and automatically assign other icon types where possible.

You should use a prefix to indicate what type of icon is being provided. Prefixed icons take the form prefix:data, with the following being valid prefixes:

Prefix	Data	Example
Base64	Base64-encoded image data	SGVsbG8gTXIgUm9ib3Q=
Encoded	Specially encoded image data	This is retained for compatibility with earlier versions of the Snarl API but is considered deprecated
File	Path to image file	file:c:\foo\bar\icons\hotdog.png
Stock	Standard Snarl stock icon	stock:misc-cheeseburger
Url	Url to the icon image to use. Recommended to use PNG icons.	url:https://cs30.ecorp.net/elliot/backdoor/robot.png

If no prefix is provided, Snarl will attempt to infer the correct type from the information provided. This is provided for backwards compatibility only however; applications should be modified to use the above prefixes.

If specifying icons using NotificationContent->Icons the prefix should not be included.

Examples

Use the stock misc-chair icon:

{
  "icon": "stock:misc-chair"
}

Use the misc-chair stock icon, but also supply a Url-based icon alternative:

{
  "icons":
    {
      "stock": "misc-chair",
      "url": "https://cs30.ecorp.net/icons/chair.png"
    }
}

Callbacks