/*
 * 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 "nsISupports.idl"
#include "nsISimpleEnumerator.idl"
#include "nsIStringEnumerator.idl"
#include "nsIRDFDataSource.idl"
#include "nsIRDFNode.idl"

#include "flockIError.idl"
#include "flockIWebService.idl"


/**
 * Used for automatic detection for blog API on self-hosted blogs.
 *
 * @see flockICustomBlogWebService#detectAccount
 */
[scriptable, uuid(78b76670-a8db-4fea-adbe-54ab509aa467)]
interface flockIBlogLink: nsISupports {
  attribute AString href;
  attribute AString rel;
  attribute AString type;
  attribute AString title;
};

/**
 * A category already existing on a blog
 *
 * @see flockIBlogWebService
 */
[scriptable, uuid(73c5d97d-c715-439a-86c9-3086b4576a46)]
interface flockIBlogCategory: nsISupports {
  /**
   * id of the category internal to the server. It may be a numeric
   * value for the server, but Flock treats it as a string.
   */
  attribute AString id;

  /** Human readable category label, eg. "sports" or "movies" */
  attribute AString label;
};


/**
 * A post to be published to a blog
 *
 * @see flockIBlogWebService#newPost
 * @see flockIBlogWebService#editPost
 */
[scriptable, uuid(81fc5b1e-c739-4b12-94f9-a9bf6d9938fe)]
interface flockIBlogPost: nsISupports {
  /**
   * The id on the server. May be null if this is a new post,
   * but either this or editURI must be set if the user want to
   * update/replace an existing post
   */
  attribute AString postid;

  /**
   * The editURI on the server. May be null if this is a new post,
   * but either this or postid must be set if the user want to
   * update/replace an existing post
   *
   * @see flockIBlogWebService#newPost
   * @see flockIBlogWebService#editPost
   */
  attribute AString editURI;

  /** The post title. May be null. */
  attribute AString title;

  /** The post description. May be null. */
  attribute AString description;

  /**
   * The publishing date, in a format dependant on the service.
   * To be left null for new posts.
   */ 
  attribute AString issued;

  /**
   * Tags to be associated to the post. If the service supports tags native
   * tags are used, otherwise Technorati tags are inserted at the end of the post.
   *
   * Elements of the nsIStringEnumerator are of type AString.
   */ 
  attribute nsIStringEnumerator tags;

  /**
   * Categories to be associated to the post. Has no effect for services that don't
   * support categories.
   *
   * Elements of the nsIStringEnumerator are of type flockIBlogCategory.
   *
   * @see flockIBlogCategory
   */
  attribute nsISimpleEnumerator categories;

  /**
   * Additional attributes, specific to the service: privacy, moods...
   *
   * Elements of the nsIStringEnumerator are of type AString.
   */
  attribute nsIStringEnumerator extra;
};


[scriptable, uuid(7a3280f6-b57c-4f27-897c-61651b6c0343)]
interface flockIBlogPublishListener: nsISupports {
  void onResult(in AString permalink);
  void onFault(in flockIError fault);
  void onError(in flockIError error);
};


[scriptable, uuid(1405ac69-d6d0-4fd4-b55a-36ec8274153f)]
interface flockIBlogListener: nsISupports {
  void onResult(in nsISimpleEnumerator aSimpleEnum);
  void onFault(in flockIError fault);
  void onError(in flockIError error);
};


/**
 * Represents a web service that supports blogging.
 *
 * @see flockIBlogAccount
 */
[scriptable, uuid(1a95c7f7-b96a-41ed-a009-318ef45add6c)]
interface flockIBlogWebService : flockILoginWebService {
  const long CATEGORIES_NO = 0;
  const long CATEGORIES_SINGLE = 1;
  const long CATEGORIES_MULTIPLE = 2;
  attribute long supportsCategories;

  /**
   * Tells whether the service supports one category per post, multiple categories
   * or no categories at all
   */
  attribute boolean supportsPostReplace;

  /**
   * Chrome URL of the XUL file to be overlayed to the blog publishing metadata
   * window, to add service-specific features (privacy, mood...)
   */
  attribute AString metadataOverlay;
  attribute AString authtoken;

  /**
   * Call the server to retrieve the list of blog of a user. The list is
   * returned through flockIBlogListener: on success,
   * flockIBlogListener.onSuccess(blogList, null) is called where blogList is a
   * nsISimpleEnumerator of nsIPropertyBag having the following properties:
   *  string title
   *  string blogID
   *  string APILink
   *  string URL
   *
   * @see nsISimpleEnumerator
   */
  void getUsersBlogs(in flockIBlogListener aBlogListener,
                     in AString aAPILink,
                     in AString aUsername,
                     in AString aPassword);

  /**
   * Call the server to retrieve the last published post on a blog
   */
  void getRecentPosts(in flockIBlogListener aBlogListener,
                      in AString aBlogId,
                      in PRUint32 aNumber);

  void getCategoryList(in flockIBlogListener aBlogListener,
                       in AString aBlogId);

  /**
   * Call the server to retrieve the last published post on a blog.
   *
   * @param aPublishListener (in) a listener to respond to successful
   *        publication or error
   * @param aBlogId (in) The blogid (as the server would understand)
   * @param aPost (in) A flockIBlogPost holding the content of the post (title, body...)
   * @param aPublish (in) true to publish directly, false to publish as a draft
   * @param aNotification (in) list of URL to notifify of the new post
   */
  void newPost(in flockIBlogPublishListener aPublishListener,
               in AString aBlogId,
               in flockIBlogPost aPost,
               in boolean aPublish,
               in nsIStringEnumerator aNotifications);

  /**
   * Call the server to retrieve the last published post on a blog
   *
   * @param aPublishListener (in) a listener to respond to successful
   *        publication or error
   * @param aBlogId (in) The blogid (as the server would understand)
   * @param aPost (in) A flockIBlogPost holding the content of the post (title, body...).
   *                   It should also contain the postid to specify the post to replace
   * @param aPublish (in) true to publish directly, false to publish as a draft
   * @param aNotification (in) list of URL to notifify of the new post
   */
  void editPost(in flockIBlogPublishListener aPublishListener,
                in AString aBlogId,
                in flockIBlogPost aPost,
                in boolean aPublish,
                in nsIStringEnumerator aNotifications);

  /**
   * For the given post, remove all categories and replace them by a new set
   *
   * @param aPublishListener (in) a listener to respond to successful
   *        publication or error
   * @param aAccount (in) The account info (auth info)
   * @param aPostId (in) The postid (as the server would understand)
   * @param aCategories (in) The new categories to set
   */
  void setPostCategories(in flockIBlogPublishListener aPublishListener,
                         in AString aBlogId,
                         in AString aPostId,
                         in nsISimpleEnumerator aCategories);
};


/**
 * This interface is used for blog API such as ATOM, Metaweblog or MovableType.
 * It adds attributes to register themselves to the blog service (for
 * autodetection) and a detectAccount method to see if the API is supported for
 * a given blog.
 *
 * Some flockIBlogWebService may mirror their calls to an API. For example, the
 * WordPress service (a flockIBlogWebService) is mirroring all its server calls
 * to the MovableType API service (a flockICustomBlogWebService).
 */
[scriptable, uuid(c65e850a-579d-4f0c-ac60-5c8ae709e5ec)]
interface flockICustomBlogWebService : flockIBlogWebService {
  attribute AString name;

  /**
   * Detect an account in a collection of links
   * @param aUrl (in): the URL of the blog
   * @param aLinkList (in): an enumerator of flockIBlogLink
   * @return a wrapped JS object with the following members:
   *
   * @see flockIBlogLink
   */
  nsISupports detectAccount(in AString aUrl, in nsISimpleEnumerator aLinkList);
};


/**
 * Represents an account with a blog web service.
 *
 * More documentation here:
 * http://developer.flock.com/wiki/Accounts_Management
 *
 * @see flockIBlogWebService
 */
[scriptable, uuid(47027282-1234-49a8-8e81-dfcddad69dad)]
interface flockIBlogAccount : flockIWebServiceAccount {
};
