/*
 * BEGIN FLOCK GPL
 *
 * Copyright Flock Inc. 2005-2008
 * 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 "flockIListener.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 single blog on a service. If the user has several blogs on a service,
 * as many flockIBlogAccount are going to be created.
 *
 * @see flockIBlogWebService
 */
[scriptable, uuid(ce875203-d39c-40b0-8f01-b2313b49bb5e)]
interface flockIBlogAccount: nsISupports {
  attribute AString title;
  attribute AString favicon;
  attribute AString uid;
  attribute AString URL;
  attribute AString api;
  attribute AString username;
  attribute AString password;
  attribute AString authtoken;
  attribute AString pwhost;
  attribute AString apiLink;
  attribute AString blogid;
};


/**
 * 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 aResult);
  void onFault (in flockIError fault);
  void onError (in flockIError error);
};


/**
 * Represents a web service that supports blogging.
 *
 * @see flockIBlogWebServiceAccount
 */
[scriptable, uuid(6DA58F50-48EC-11DB-B0DE-0800200C9A66)]
interface flockIBlogWebService : flockIWebService {
  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;

  /*
   * Return the list of blogs already configured for the given service
   * Each element is a flockIBlog
   */
  nsISimpleEnumerator getBlogs();

  /**
   * Initialize the service. You normally don't need to call this method
   */
  void init ();

  /**
   * Call the server to retrieve the list of blog of a user. The list is returned
   * through aListener: on success, aListener.onSuccess(blogList, null) is called
   * where blogList is a nsISimpleEnumerator of flockIBlogAccount.
   *
   * @see nsISimpleEnumerator
   * @see nsIBlogAccount
   */
  void getUsersBlogs (in flockIListener aListener, in flockIBlogAccount aAccount);
  /**
   * Call the server to retrieve the last published post on a blog
   */
  void getRecentPosts (in flockIBlogListener aListener, in AString aBlogId,
                       in PRUint32 aNumber);
  void getCategoryList (in flockIBlogListener aListener, in AString aBlogId);
  /**
   * Call the server to retrieve the last published post on a blog
   * @param aListener (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
   * @return nothing
   */
  void newPost (in flockIBlogPublishListener aListener, 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 aListener (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
   * @return nothing
   */
  void editPost (in flockIBlogPublishListener aListener, 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 aListener (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
   * @return nothing
   */
  void setPostCategories (in flockIBlogPublishListener aListener, in flockIBlogAccount aAccount,
                      in AString aPostId, in nsISimpleEnumerator aCategories);

};

/**
 * This interface is used for blog API such as ATOM, Metaweblog or MovableType.
 * It adda 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
   * aLinkList should be an enumerator of flockIBlogLink
   *
   * @see flockIBlogLink
   */
  flockIBlogAccount 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(414A77D0-48ED-11DB-B0DE-0800200C9A66)]
interface flockIBlogWebServiceAccount : flockIWebServiceAccount {
  nsISimpleEnumerator getBlogs();
};
