michael@0: /* vim: sw=2 ts=2 et lcs=trail\:.,tab\:>~ :
michael@0:  * This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #ifndef mozilla_places_SQLFunctions_h_
michael@0: #define mozilla_places_SQLFunctions_h_
michael@0: 
michael@0: /**
michael@0:  * This file contains functions that Places adds to the database handle that can
michael@0:  * be accessed by SQL queries.
michael@0:  *
michael@0:  * Keep the GUID-related parts of this file in sync with
michael@0:  * toolkit/downloads/SQLFunctions.[h|cpp]!
michael@0:  */
michael@0: 
michael@0: #include "mozIStorageFunction.h"
michael@0: #include "mozilla/Attributes.h"
michael@0: 
michael@0: class mozIStorageConnection;
michael@0: 
michael@0: namespace mozilla {
michael@0: namespace places {
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //// AutoComplete Matching Function
michael@0: 
michael@0: /**
michael@0:  * This function is used to determine if a given set of data should match an
michael@0:  * AutoComplete query.
michael@0:  *
michael@0:  * In SQL, you'd use it in the WHERE clause like so:
michael@0:  * WHERE AUTOCOMPLETE_MATCH(aSearchString, aURL, aTitle, aTags, aVisitCount,
michael@0:  *                          aTyped, aBookmark, aOpenPageCount, aMatchBehavior,
michael@0:  *                          aSearchBehavior)
michael@0:  *
michael@0:  * @param aSearchString
michael@0:  *        The string to compare against.
michael@0:  * @param aURL
michael@0:  *        The URL to test for an AutoComplete match.
michael@0:  * @param aTitle
michael@0:  *        The title to test for an AutoComplete match.
michael@0:  * @param aTags
michael@0:  *        The tags to test for an AutoComplete match.
michael@0:  * @param aVisitCount
michael@0:  *        The number of visits aURL has.
michael@0:  * @param aTyped
michael@0:  *        Indicates if aURL is a typed URL or not.  Treated as a boolean.
michael@0:  * @param aBookmark
michael@0:  *        Indicates if aURL is a bookmark or not.  Treated as a boolean.
michael@0:  * @param aOpenPageCount
michael@0:  *        The number of times aURL has been registered as being open.  (See
michael@0:  *        mozIPlacesAutoComplete::registerOpenPage.)
michael@0:  * @param aMatchBehavior
michael@0:  *        The match behavior to use for this search.
michael@0:  * @param aSearchBehavior
michael@0:  *        A bitfield dictating the search behavior.
michael@0:  */
michael@0: class MatchAutoCompleteFunction MOZ_FINAL : public mozIStorageFunction
michael@0: {
michael@0: public:
michael@0:   NS_DECL_THREADSAFE_ISUPPORTS
michael@0:   NS_DECL_MOZISTORAGEFUNCTION
michael@0: 
michael@0:   /**
michael@0:    * Registers the function with the specified database connection.
michael@0:    *
michael@0:    * @param aDBConn
michael@0:    *        The database connection to register with.
michael@0:    */
michael@0:   static nsresult create(mozIStorageConnection *aDBConn);
michael@0: 
michael@0: private:
michael@0:   /**
michael@0:    * Argument Indexes
michael@0:    */
michael@0:   static const uint32_t kArgSearchString = 0;
michael@0:   static const uint32_t kArgIndexURL = 1;
michael@0:   static const uint32_t kArgIndexTitle = 2;
michael@0:   static const uint32_t kArgIndexTags = 3;
michael@0:   static const uint32_t kArgIndexVisitCount = 4;
michael@0:   static const uint32_t kArgIndexTyped = 5;
michael@0:   static const uint32_t kArgIndexBookmark = 6;
michael@0:   static const uint32_t kArgIndexOpenPageCount = 7;
michael@0:   static const uint32_t kArgIndexMatchBehavior = 8;
michael@0:   static const uint32_t kArgIndexSearchBehavior = 9;
michael@0:   static const uint32_t kArgIndexLength = 10;
michael@0: 
michael@0:   /**
michael@0:    * Typedefs
michael@0:    */
michael@0:   typedef bool (*searchFunctionPtr)(const nsDependentCSubstring &aToken,
michael@0:                                     const nsACString &aSourceString);
michael@0: 
michael@0:   typedef nsACString::const_char_iterator const_char_iterator;
michael@0: 
michael@0:   /**
michael@0:    * Obtains the search function to match on.
michael@0:    *
michael@0:    * @param aBehavior
michael@0:    *        The matching behavior to use defined by one of the
michael@0:    *        mozIPlacesAutoComplete::MATCH_* values.
michael@0:    * @return a pointer to the function that will perform the proper search.
michael@0:    */
michael@0:   static searchFunctionPtr getSearchFunction(int32_t aBehavior);
michael@0: 
michael@0:   /**
michael@0:    * Tests if aSourceString starts with aToken.
michael@0:    *
michael@0:    * @param aToken
michael@0:    *        The string to search for.
michael@0:    * @param aSourceString
michael@0:    *        The string to search.
michael@0:    * @return true if found, false otherwise.
michael@0:    */
michael@0:   static bool findBeginning(const nsDependentCSubstring &aToken,
michael@0:                             const nsACString &aSourceString);
michael@0: 
michael@0:   /**
michael@0:    * Tests if aSourceString starts with aToken in a case sensitive way.
michael@0:    *
michael@0:    * @param aToken
michael@0:    *        The string to search for.
michael@0:    * @param aSourceString
michael@0:    *        The string to search.
michael@0:    * @return true if found, false otherwise.
michael@0:    */
michael@0:   static bool findBeginningCaseSensitive(const nsDependentCSubstring &aToken,
michael@0:                                          const nsACString &aSourceString);
michael@0: 
michael@0:   /**
michael@0:    * Searches aSourceString for aToken anywhere in the string in a case-
michael@0:    * insensitive way.
michael@0:    *
michael@0:    * @param aToken
michael@0:    *        The string to search for.
michael@0:    * @param aSourceString
michael@0:    *        The string to search.
michael@0:    * @return true if found, false otherwise.
michael@0:    */
michael@0:   static bool findAnywhere(const nsDependentCSubstring &aToken,
michael@0:                            const nsACString &aSourceString);
michael@0: 
michael@0:   /**
michael@0:    * Tests if aToken is found on a word boundary in aSourceString.
michael@0:    *
michael@0:    * @param aToken
michael@0:    *        The string to search for.
michael@0:    * @param aSourceString
michael@0:    *        The string to search.
michael@0:    * @return true if found, false otherwise.
michael@0:    */
michael@0:   static bool findOnBoundary(const nsDependentCSubstring &aToken,
michael@0:                              const nsACString &aSourceString);
michael@0: 
michael@0: 
michael@0:   /**
michael@0:    * Fixes a URI's spec such that it is ready to be searched.  This includes
michael@0:    * unescaping escaped characters and removing certain specs that we do not
michael@0:    * care to search for.
michael@0:    *
michael@0:    * @param aURISpec
michael@0:    *        The spec of the URI to prepare for searching.
michael@0:    * @param aMatchBehavior
michael@0:    *        The matching behavior to use defined by one of the
michael@0:    *        mozIPlacesAutoComplete::MATCH_* values.
michael@0:    * @param _fixedSpec
michael@0:    *        An out parameter that is the fixed up string.
michael@0:    */
michael@0:   static void fixupURISpec(const nsCString &aURISpec, int32_t aMatchBehavior,
michael@0:                            nsCString &_fixedSpec);
michael@0: };
michael@0: 
michael@0: 
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //// Frecency Calculation Function
michael@0: 
michael@0: /**
michael@0:  * This function is used to calculate frecency for a page.
michael@0:  *
michael@0:  * In SQL, you'd use it in when setting frecency like:
michael@0:  * SET frecency = CALCULATE_FRECENCY(place_id).
michael@0:  * Optional parameters must be passed in if the page is not yet in the database,
michael@0:  * otherwise they will be fetched from it automatically.
michael@0:  *
michael@0:  * @param pageId
michael@0:  *        The id of the page.  Pass -1 if the page is being added right now.
michael@0:  * @param [optional] typed
michael@0:  *        Whether the page has been typed in.  Default is false.
michael@0:  * @param [optional] fullVisitCount
michael@0:  *        Count of all the visits (All types).  Default is 0.
michael@0:  * @param [optional] isBookmarked
michael@0:  *        Whether the page is bookmarked. Default is false.
michael@0:  */
michael@0: class CalculateFrecencyFunction MOZ_FINAL : public mozIStorageFunction
michael@0: {
michael@0: public:
michael@0:   NS_DECL_THREADSAFE_ISUPPORTS
michael@0:   NS_DECL_MOZISTORAGEFUNCTION
michael@0: 
michael@0:   /**
michael@0:    * Registers the function with the specified database connection.
michael@0:    *
michael@0:    * @param aDBConn
michael@0:    *        The database connection to register with.
michael@0:    */
michael@0:   static nsresult create(mozIStorageConnection *aDBConn);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * SQL function to generate a GUID for a place or bookmark item.  This is just
michael@0:  * a wrapper around GenerateGUID in Helpers.h.
michael@0:  *
michael@0:  * @return a guid for the item.
michael@0:  */
michael@0: class GenerateGUIDFunction MOZ_FINAL : public mozIStorageFunction
michael@0: {
michael@0: public:
michael@0:   NS_DECL_THREADSAFE_ISUPPORTS
michael@0:   NS_DECL_MOZISTORAGEFUNCTION
michael@0: 
michael@0:   /**
michael@0:    * Registers the function with the specified database connection.
michael@0:    *
michael@0:    * @param aDBConn
michael@0:    *        The database connection to register with.
michael@0:    */
michael@0:   static nsresult create(mozIStorageConnection *aDBConn);
michael@0: };
michael@0: 
michael@0: /**
michael@0:  * SQL function to unreverse the rev_host of a page.
michael@0:  *
michael@0:  * @param rev_host
michael@0:  *        The rev_host value of the page.
michael@0:  *
michael@0:  * @return the unreversed host of the page.
michael@0:  */
michael@0: class GetUnreversedHostFunction MOZ_FINAL : public mozIStorageFunction
michael@0: {
michael@0: public:
michael@0:   NS_DECL_THREADSAFE_ISUPPORTS
michael@0:   NS_DECL_MOZISTORAGEFUNCTION
michael@0: 
michael@0:   /**
michael@0:    * Registers the function with the specified database connection.
michael@0:    *
michael@0:    * @param aDBConn
michael@0:    *        The database connection to register with.
michael@0:    */
michael@0:   static nsresult create(mozIStorageConnection *aDBConn);
michael@0: };
michael@0: 
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //// Fixup URL Function
michael@0: 
michael@0: /**
michael@0:  * Make a given URL more suitable for searches, by removing common prefixes
michael@0:  * such as "www."
michael@0:  *
michael@0:  * @param url
michael@0:  *        A URL.
michael@0:  * @return
michael@0:  *        The same URL, with redundant parts removed.
michael@0:  */
michael@0: class FixupURLFunction MOZ_FINAL : public mozIStorageFunction
michael@0: {
michael@0: public:
michael@0:   NS_DECL_THREADSAFE_ISUPPORTS
michael@0:   NS_DECL_MOZISTORAGEFUNCTION
michael@0: 
michael@0:   /**
michael@0:    * Registers the function with the specified database connection.
michael@0:    *
michael@0:    * @param aDBConn
michael@0:    *        The database connection to register with.
michael@0:    */
michael@0:   static nsresult create(mozIStorageConnection *aDBConn);
michael@0: };
michael@0: 
michael@0: 
michael@0: ////////////////////////////////////////////////////////////////////////////////
michael@0: //// Frecency Changed Notification Function
michael@0: 
michael@0: /**
michael@0:  * For a given place, posts a runnable to the main thread that calls
michael@0:  * onFrecencyChanged on nsNavHistory's nsINavHistoryObservers.  The passed-in
michael@0:  * newFrecency value is returned unchanged.
michael@0:  *
michael@0:  * @param newFrecency
michael@0:  *        The place's new frecency.
michael@0:  * @param url
michael@0:  *        The place's URL.
michael@0:  * @param guid
michael@0:  *        The place's GUID.
michael@0:  * @param hidden
michael@0:  *        The place's hidden boolean.
michael@0:  * @param lastVisitDate
michael@0:  *        The place's last visit date.
michael@0:  * @return newFrecency
michael@0:  */
michael@0: class FrecencyNotificationFunction MOZ_FINAL : public mozIStorageFunction
michael@0: {
michael@0: public:
michael@0:   NS_DECL_THREADSAFE_ISUPPORTS
michael@0:   NS_DECL_MOZISTORAGEFUNCTION
michael@0: 
michael@0:   /**
michael@0:    * Registers the function with the specified database connection.
michael@0:    *
michael@0:    * @param aDBConn
michael@0:    *        The database connection to register with.
michael@0:    */
michael@0:   static nsresult create(mozIStorageConnection *aDBConn);
michael@0: };
michael@0: 
michael@0: 
michael@0: } // namespace places
michael@0: } // namespace storage
michael@0: 
michael@0: #endif // mozilla_places_SQLFunctions_h_