/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2009
 * http://flock.com
 *
 * This file may be used under the terms of the
 * GNU General Public License Version 2 or later (the "GPL"),
 * http://www.gnu.org/licenses/gpl.html
 *
 * Software distributed under the License is distributed on an "AS IS" basis,
 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
 * for the specific language governing rights and limitations under the
 * License.
 *
 * END FLOCK GPL
 */

#include "flockIError.idl"
#include "flockIListener.idl"
#include "nsISupports.idl"
#include "nsILoginInfo.idl"

/**
 * Represents a web service API.  When implementing calls to an API, the code
 * should be encapsulated in a separate XPCOM component... *not* an XPCOM service,
 * because we may want multple instances of it.
 *
 * Generally the web service component will hold a copy of the API as a private
 * member varible.
 *
 * @see flockIWebService
 */
[scriptable, uuid(ea6e9ce2-ae22-4708-a27a-6750efcd8cfc)]
interface flockIWebServiceAPI : nsISupports {
  /**
   * Call the aMethod, supplying the parameters in aParams.  In the case of
   * authenticated APIs, this is generally an authenticated call whenever
   * possible.  If the call fails for any reason, including invalid
   * authentication, then aFlockListener.onError() will be called with the details.
   *
   * @param aApiMethod Name of the API method to be called.
   * @param aParams aParams.wrappedJSObject is an associative array of
   *                parameters.
   * @param aPostVars aPostVars.wrappedJSObject is an associative array of
   *                  parameters.
   * @param aRequestMethod Request method (GET, POST, PUT, etc.) indicated by
   *                       constants.
   * @param aFlockListener Listener to respond to success or failure events.
   * @see GET
   * @see PUT
   * @see POST
   */
  void call(in AString aApiMethod,
            in nsISupports aParams,
            in nsISupports aPostVars,
            in long aRequestMethod,
            in flockIListener aFlockListener);

  const long GET = 0;
  const long PUT = 1;
  const long POST = 2;

  /**
   * Maps above constants to strings that nsIXMLHttpRequest can understand.
   *
   * @param aRequestType using constants.
   * @return AString of the request method that nsIXMLHttpRequest understands.
   * @see nsIXMLHttpRequest
   * @see GET
   * @see PUT
   * @see POST
   */
  AString getRequestMethod(in long aRequestMethod);

  /**
   * Maps API error codes to a flockIError object.
   *
   * @param aErrorCode (in) API error code.
   * @return an flockIError object.
   */
  flockIError getError(in AString aErrorCode);

  /**
   * Maps API HTTP error codes to flockIError object.
   *
   * @param aHttpErrorCode (in) API HTTP error code.
   * @return an flockIError object.
   */
  flockIError getHttpError(in AString aHttpErrorCode);
};


/**
 * A web service API that supports authentication and authenticated calls.
 */
[scriptable, uuid(824ca3ca-e555-4c63-af3c-15db59923379)]
interface flockIAuthenticatedAPI : flockIWebServiceAPI {
  /**
   * Authenticate the API.
   * @param aLoginInfo (in) Username and password to authenticate with the
   *        API.  The API component may not actually use it if, for example, a
   *        valid token is still held.  In cases where the password is not
   *        required, null is an acceptable input.  Some APIs may hold the
   *        credentials and pass them with every authenticated call.
   * @param aFlockListener (in) Listener to respond to success or failure events.
   */
  void authenticate(in nsILoginInfo aLoginInfo,
                    in flockIListener aFlockListener);

  /** Deauthenticate the API.  */
  void deauthenticate();
};


/**
 * Token-based authentication API.
 */
[scriptable, uuid(922CB12E-E49A-4737-A2C2-9ECC993C1B2E)]
interface flockITokenAPI : flockIAuthenticatedAPI {
  /** Token value used for authenticated calls */
  readonly attribute AString token;

  /** Token expiration date: the number of milliseconds since 01/01/1970. */
  readonly attribute PRUint32 expiresOn;
};
