/*
 * Licensed to OMTP Ltd. (OMTP) under one or more contributor license agreements. 
 * See the NOTICE file distributed with this work for additional information regarding 
 * copyright ownership. 
 * 
 * The Reference Implementation (save for such parts of the reference implementation made 
 * available under separate terms and conditions) is made available under the terms of the 
 * Apache License, version 2.0, subject to the condition that any "Works" and "Derivative 
 * Works" used or distributed for commercial purposes must be and remain compliant with the
 * BONDI specification as promulgated by OMTP in each release. Your implementation of the 
 * Reference Implementation (whether object or source) must maintain these conditions, and 
 * you must notify any recipient of this condition in a conspicuous way.
 * 
 * You may not use this BONDI Reference Implementation except in compliance with the License. 
 * 
 * You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 or at 
 * http://bondi.omtp.org/BONDI-LICENSE-2.0 
 * 
 */

/**
 * \brief BONDI Push API
 *
 * This API provides functionality of OMA Push delivery to Web Applications
 * running in the widget context, which includes; subscription/unsubscription 
 * of web applications to Push messages from the OMA Push enabler, and delivery 
 * of received Push messages to the subscribeed application(s). 
 * 
 * This module offers the functionality to subscribe to OMA Push messages.
 * A subscription to Push messages will remain active until explicit unsubscription.
 * While subscribed, Push messages that match application preferences will be delivered 
 * to the application if possible, through a call to the application-defined Push message
 * listener.
 * 
 * The basic structure of OMA Push messages is very similar to HTTP messages, i.e. they 
 * include headers and a content body.
 * 
 * Headers:
 * <ul>
 *   <li>Push Application ID: an OMNA-registered value for BONDI "x-oma-bondi:widget.ua", 
 *   (see <a href="http://www.openmobilealliance.org/Tech/omna/omna-push-app-id.aspx">OMA Push Application ID Registry</a>), which is 
 *    used by OMA Push Clients to route incoming Push to the widget user agent.</li>
 *   <li>Content Type: MIME type of the Push body.</li>
 *   <li>Other headers (application specific or standardized).</li>
 * </ul>
 * Content:
 * <ul>
 *   <li>Content: may be a text or binary file. Text files may be in plain text
 *       XML, or any other text content type. Text files may be delivered to the 
 *       terminal in compressed form (e.g. content encoding as WBXML or GZIP), 
 *       and will be uncompressed before delivery to the subscribed application.
 *       OMA Push defines standard XML-based content types of general use for
 *       notification/wakeup-type purposes, e.g. the <a href="http://member.openmobilealliance.org/ftp/Public_documents/cd/Permanent_documents/OMA-WAP-167_ServiceInd-V2_2-20010731-A.zip">"Service Indication"</a> and 
 *       <a href="http://member.openmobilealliance.org/ftp/Public_documents/cd/Permanent_documents/OMA-WAP-168_ServiceLoad-V2_2-20010731-A.zip">"Service Loading"</a> content types.</li>
 * </ul>
 * 
 * OMA Push messages are delivered via various bearers and protocols, depending upon the
 * support of the specific device. The specific bearer used is transparent to the
 * application, except as arranged through a specific Push Registration URI (a 
 * parameter of the subscription process). 
 *
 * The latest OMA Push Candidate Enabler release is <a href="http://www.openmobilealliance.org/Technical/release_program/push_v2_3.aspx">OMA Push 2.3</a>.
 * OMA Push "Over-the-Air" protocol reference: <a href="http://member.openmobilealliance.org/ftp/Public_documents/cd/Permanent_documents/OMA-TS-PushOTA-V2_3-20100224-D.zip">Push-OTA</a>
 *
 * \def-api-feature http://bondi.omtp.org/api/push.subscribe
 * \brief Subscribe for access to Push messages
 * \device-cap push
 *
 * \def-api-feature-set http://bondi.omtp.org/api/push
 * \brief All the Push features
 * \api-feature http://bondi.omtp.org/api/push.subscribe
 *
 * \def-device-cap push
 * \brief Subscribe for access to Push messages
 * \param appid Push Application ID to be subscribed to. The parameter can be used to
 *				restrict access to events meant for certain application types, e.g. 
 *				OMA-standardized Push applications (browsing, Multimedia Messaging
 *				(MMS), Instant Messaging (IM), Device Management (DM), etc.) by 
 *				blocking subscription to appid values prefixed by "x-wap" or "x-oma".
 * \param accept Content (MIME) types to be subscribed to. The parameter can be used to
 *				restrict access to content intended for a specific pre-define handler,
 *				e.g. OMA-standardized Push applications (MMS notifications, IM 
 *				notifications, DM notifications, etc) by blocking subscription
 *				to MIME types associated with those applications.
 * \param exclusive Request exclusive subscription to the selected parameters. The
 *				parameter can be used to ensure that only a single application can
 *				act as a handler for the event types. Note that the user agent will
 *				deny exclusive subscription if that conflicts with device-native 
 *				clients (e.g. browsing, MMS, IM, DM, etc).
 * 
 * \author Bryan Sullivan &lt;bryan.sullivan@att.com&gt;
 * \version 0.3
 */
module push {

	/**
	 * \brief The success callback for subscription to incoming Push messages.
	 *
	 * This callback completes the asynchronous operation initiated by the 
	 * subscribe() method, confirms successful subscription to the requested
	 * Push message events, and provides the subscription ID that can be used to
	 * cancel the subscription at a later time, via the unsubscribe() method.
	 *
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface SubscriptionSuccessCallback {
		/**
		 * \brief Method invoked when subscribing is successful
		 *
		 * \param subscriptionID Identifier of the subscription
		 */
		void onSuccess(in unsigned long subscriptionID);
	};

	/**
	 * \brief Push message callback
	 *
	 * Callback for incoming Push messages.
	 * When the callback is invoked its input parameters are the 
	 * Push message header array and content.
	 */
	[Callback=FunctionOnly, NoInterfaceObject] interface PushEventCallback {
	   /**
	    * \brief Method invoked to notify about incoming Push message
	    *
	    * \param message The Push message
	    */
		void onPushEvent(in PushMessage message);
	};
	
	/**
	 * \brief Manager class exposed as the Push module API.
	 *
	 * This manager class exposes the Push base API, such as
	 * subscribing to OMA Push message events, delivering received Push 
	 * message events, and unsubscribing to Push message events.
	 *
 	 * \code
	 *  var subscriptionID = 0;
 	 *
	 *	// Define the success callback to get the subscription ID.
	 * 	function successCallback(id) {
	 * 		subscriptionID = id;
	 * 	}
	 *
	 *	// Define the error callback.
	 * 	function errorCallback(response) {
	 * 		alert( "Push subscription failed. The error code is: " +  response.code);
	 * 	}
	 *
	 *	// Define listener for received Push messages
	 *	function gotPush(push) {
	 *		var ctype = push.getMessageHeader("Content-Type");
	 *		if (ctype == "text/vnd.wap.si") {
	 *			serviceIndication(push.messageXML);
	 *		}
	 *		if (ctype == "text/vnd.wap.sl") {
	 *			serviceLoad(push.messageXML);
	 *		}
	 *		(... etc for other content types as supported by widget)
	 *	}
	 *
	 *	// Subscribe to Push messages
	 * 	var accept = "text/vnd.wap.si";
	 * 	var appid = "x-oma-application:dcd.ua";
	 * 	var pendop = bondi.push.subscribe(successCallback, errorCallback, 
	 *  			gotPush, registrationUri, accept, appid, false);
	 *
	 *	// Cancel subscription to Push messages
 	 * 	bondi.push.unsubscribe(subscriptionID);
 	 *
 	 * \endcode
	 */
	 interface PushManager {
		/**
		 * \brief Method for subscription to Push events.
		 *
		 * This API allows applications to be notified whenever an incoming Push
		 * meets a set of conditions. The returned identifier may be used to 
		 * unsubscribe from these events using the unsubscribe method.
		 *
		 * The accept is optional, and can be used by the widget to request 
		 * notification for specific content (MIME) types only.
		 *
		 * The callback argument is mandatory. Whenever a Push message is 
		 * received the system will call the supplied callback passing
		 * the Push message object.
		 * 
		 * If the widget is not authorized to subscribe for Push messages,
		 * a SecurityError with code PERMISSION_DENIED_ERROR will be raised.
		 * 
		 * If the implementation has not implemented the API, a 
		 * DeviceAPIError with code NOT_SUPPORTED_ERROR will be raised.
		 *
		 * \def-api-feature http://bondi.omtp.org/api/push
		 * \brief Subscribe to Push messages
		 * 
		 * \code
         * 	var pendop = bondi.push.subscribe(successCallback, errorCallback, 
         *               gotPush, registrationUri, accept, appid, false);
		 * \endcode    
		 * 
		 * \param successCallback function called when the invocation
		 *        ends successfully, use response object to retrieve subscription identifier
		 * \param errorCallback function called when an error occurs,
		 *        the callback provides an input parameter that is an Error object
		 * \param listener Callback to be invoked whenever an 
		 *        applicable Push message is received.
		 * \param registrationUri The address to which the Push Service Registration procedure [OMA PushOTA]
		 *        should be executed, e.g. to receive applicable connection profiles for the Push service.
		 * \param accept The set of content (MIME) types for which the
		 *        widget should be notified. Case-insensitive.
		 * \param appid The OMNA-registered or unregistered Push Application ID 
		 *        URN associated with the web application. Case-insensitive.
		 * \param exclusive Allows a widget for requesting exclusive subscription for
		 *        the notifications. If set to true no other application could
		 *        subscribe to these notifications.
		 * \return PendingOperation enabling the requester to cancel this request.
		 * \throw SecurityError PERMISSION_DENIED_ERROR when
		 *        access is denied by the security policy, or the request is not
		 *        possible otherwise (e.g. an exclusive subscription already exists
		 *        or the appid/accept type is associated with a native client 
		 *        which has exclusive access to the type of Push messages).
		 * \throw DeviceAPIError NOT_SUPPORTED_ERROR if
		 *        the the implementation has not implemented the API.
		 */
		PendingOperation subscribe(in SubscriptionSuccessCallback successCallback, 
				in ErrorCallback errorCallback,
				in PushEventCallback listener,
				[Optional] in DOMString registrationUri,
				[Optional] in DOMString accept,
				[Optional] in DOMString appid,
				[Optional] in boolean exclusive)
			raises(SecurityError, DeviceAPIError);

		/**
		 * \brief Method to unsubscribe to Push message notifications.
		 *
		 * \code
		 * // "subscriptionID" is the ID returned upon subscription success.
		 *  bondi.push.unsubscribe(subscriptionID);
		 * \endcode
		 * \param subscriptionID Subscription identifier
		 * \throw DeviceAPIError INVALID_ARGUMENT_ERROR if an invalid
		 *        parameter is provided to this function
		 */
		void unsubscribe(in unsigned long subscriptionID)
			raises(SecurityError, DeviceAPIError);
	};

	/**
	 * \brief Push Message API
	 *
	 * The Push Message interface enables access to the headers and content of a
	 * Push message. The interface provides access to the headers as an array or
	 * to a specific header (by name), and to the message content as a string or
	 * XML document.
	 *
	 */
	interface PushMessage {

		/**
		 * \brief Get all headers of the Push message.
		 * 
		 * The getAllmessageHeaders() method returns all the Push message 
		 * headers, as a single string, with each header line separated by a 
		 * U+000D CR U+000A LF pair, and with each header name and header value 
		 * separated by a U+003A COLON U+0020 SPACE pair. If there are no 
		 * headers, the method returns null.
		 * 
		 * \code
		 * // "push" is set to a Push message object received earlier.
		 *  var headers = push.getAllMessageHeaders();
		 *  alert(headers); // show the Push message headers 
		 * \endcode
		 */
		 DOMString getAllMessageHeaders();
		 
		/**
		 * \brief Get a specific header of the Push message.
		 *
		 * The getMessageHeader(header) method returns one of:
		 * <ul>
		 * <li>If header is an ASCII case-insensitive match for multiple message 
		 *    headers, the values of these headers as a single 
		 *    concatenated string separated from each other by a U+002C COMMA 
		 *    U+0020 SPACE character pair.</li>
		 * <li>If header is an ASCII case-insensitive match for a single message
		 *    header, the value of that header.</li>
		 * <li>null.</li>
		 * </ul>
		 *
		 * \code
		 * // "push" is set to a Push message object received earlier.
		 *  var ctype = push.getMessageHeader("Content-Type");
		 *  alert(ctype); // show the Push message content type
		 * \endcode
		 * \param header Name of the header to retrieve, if present.  Case-insensitive.
		 */
		 DOMString getMessageHeader(in DOMString header);

		/**
		 * \brief Get Push message content as text.
		 *
		 * The messageText attribute returns the text response entity body
		 * (if any), as defined for XMLHttpRequest in 
		 * <a href="http://www.w3.org/TR/XMLHttpRequest/#text-response-entity-body">http://www.w3.org/TR/XMLHttpRequest/#text-response-entity-body</a>.
		 *
		 * This is a readonly property.
		 *
		 * \code
		 * // "push" is set to a Push message object received earlier.
		 *  alert(push.messageText); // show the Push message
		 * \endcode
		 */
		 readonly attribute DOMString messageText;
		 
		/**
		 * \brief Get Push message content as XML.
		 *
		 * The messageXML attribute return the XML response entity body (if any), 
		 * as defined for XMLHttpRequest in 
		 * <a href="http://www.w3.org/TR/XMLHttpRequest/#xml-response-entity-body">http://www.w3.org/TR/XMLHttpRequest/#xml-response-entity-body</a>.
		 *
		 * This is a readonly property.
		 *
		 * \code
		 * // "push" is set to a Push message object received earlier.
		 * var dcdXml = push.messageXML; // get the message as XML
		 * // get the channel metadata attribute
         * var cm = getElementAttributes(dcdXml,"Channel-Metadata",0);
		 * \endcode
		 */
		 readonly attribute Document messageXML;
	};
};