/GSearch-1.1/Src/GSearch.Patent/GPatentSearch.cs

/******************************************************************************

 * GPatentSearch.cs

 * 

 * This module implements the GPatentSearch search class and related types.

 *  

 * Date:   12/2008

 * 

 * Copyright (c) 2009, Mark Betz 

 * 

 * All rights reserved. 

 * Redistribution and use in source and binary forms, with or without 

 * modification, are permitted provided that the following conditions are met: 

 * 

 *   * Redistributions of source code must retain the above copyright 

 *     notice, this list of conditions and the following disclaimer. 

 *   * Redistributions in binary form must reproduce the above copyright 

 *     notice, this list of conditions and the following disclaimer in the 

 *     documentation and/or other materials provided with the distribution. 

 *   * Neither the name of the Author nor the names of contributors may be 

 *     used to endorse or promote products derived from this software

 *     without specific prior written permission. 

 *     

 * THIS SOFTWARE IS PROVIDED BY MARK BETZ ''AS IS'' AND ANY  EXPRESS OR

 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 

 * IN NO EVENT SHALL MARK BETZ BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,

 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;

 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,

 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR

 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF

 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

 * 

 */

using System;



namespace GSearch

{

    /// <summary>

    /// Type of the event arguments to GPatentSearch events

    /// </summary>

    public class PatentSearchEventArgs : SearchEventArgs

    {

        /// <summary>

        /// Constructor used to initialize from a SearchEventArgs object

        /// </summary>

        /// <param name="se"></param>

        public PatentSearchEventArgs(SearchEventArgs se)

            : base(se.Status, se.Result, se.Ex)

        {

        }



        /// <summary>

        /// Returns a reference to a <see cref="GSearch.GPatentResponse"/> object

        /// that contains the response, for certain event types

        /// </summary>

        public new GPatentResponse Result

        { get { return (GPatentResponse)(base.Result); } }

    }



    /// <summary>

    /// Selects the types of results returned in patent searches, where All

    /// selects all results, Filed selects filed patents only, and Issued

    /// selects issued patents only.

    /// </summary>

    public enum SearchPatentStatus

    {

        /// <summary>

        /// Select patents regardless of Status

        /// </summary>

        All,

        

        /// <summary>

        /// Selects only patents which have been filed but not issued

        /// </summary>

        Filed,

        

        /// <summary>

        /// Selects only patents which have been issued

        /// </summary>

        Issued

    };



    /// <summary>

    /// PatentSearchArgs derives from <see cref="GSearch.SearchArgs"/> and implements

    /// patent search-specific arguments.

    /// <example>

    /// The following code illustrates how to create and use the PatentSearchArgs class:

    /// <code>

    /// GPatentSearch gps = new GPatentSearch();

    /// PatentSearchArgs psa = new PatentSearchArgs();

    /// psa.Terms = "Perpetual Motion";

    /// GPatentResponse resp = gps.Search(psa);

    /// </code>

    /// </example>

    /// </summary>

    public class PatentSearchArgs : SearchArgs

    {

        /// <summary>

        /// Default constructor for the PatentSearchArgs class.

        /// </summary>

        public PatentSearchArgs()

        {

            Scoring = SearchScoring.Relevance;

            Types = SearchPatentStatus.All;

        }



        /// <summary>

        /// ToQueryString overrides the base class version. It calls the

        /// base class version to get the root of the query string, and then

        /// builds the rest of the parameters.

        /// </summary>

        /// <returns>A System.String containing the complete set of querystring

        /// arguments for the specified search</returns>

        public override string ToQueryString()

        {

            string qry = base.ToQueryString();



            if ( SearchPatentStatus.Filed == Types )

                qry += "&as_psra=1";

            else if ( SearchPatentStatus.Issued == Types )

                qry += "&as_psrg=1";

                

            if ( SearchScoring.Date == Scoring )

                qry += "&scoring=d";

            else if ( SearchScoring.DateAscending == Scoring )

                qry += "&scoring=ad";

                

            return qry;

        }



        /// <summary>

        /// A value from the <see cref="GSearch.SearchPatentStatus"/> enum giving

        /// the types of results desired from the search.

        /// </summary>

        public SearchPatentStatus Types { get; set; }

        

        /// <summary>

        /// A value from the <see cref="GSearch.SearchScoring"/> enum giving the

        /// type of ranking applied to search results.

        /// </summary>

        public SearchScoring Scoring { get; set; }

    }



    /// <summary>

    /// The GPatentSearch class provides an interface for searching patents using Google.

    /// It derives from <see cref="GSearch.GSearchCore"/> which does a large part of

    /// the work.

    /// <example>

    /// The following example shows how to use the GPatentSearch class to search for

    /// patents using Google:

    /// <code>

    /// GPatentSearch gps = new GPatentSearch();

    /// PatentSearchArgs psa = new PatentSearchArgs();

    /// psa.Terms = "Perpetual Motion";

    /// GPatentResponse resp = gps.Search(psa);

    /// if ( resp.Response.Results.Length > 0 )

    ///     // process results

    /// </code>

    /// </example>

    /// </summary>

    public class GPatentSearch : GSearchCore

    {

#if (!SILVERLIGHT)

        /// <summary>

        /// Performs a syncronous search for patents using the supplied arguments. The

        /// calling thread blocks until results are returned or an exception is thrown.

        /// This method is not available in the Silverlight version of the libraries.

        /// </summary>

        /// <param name="args"><see cref="GSearch.PatentSearchArgs"/> containing the search arguments</param>

        /// <returns><see cref="GSearch.GPatentResponse"/> containing the results</returns>

        /// <exception cref="Exception">if an error occurs during the search</exception>

        public GPatentResponse Search(PatentSearchArgs args)

        {

            return (GPatentResponse)base.Search(args);

        }

#endif



        /// <summary>

        /// Peforms an asyncronous search for patents using the supplied arguments. The

        /// calling thread returns immediately, and results or errors are indicated by

        /// raising the SearchFailed, SearchComplete, or SearchProgressChanged events.

        /// Results are returned on the UI thread.

        /// </summary>

        /// <param name="args"><see cref="GSearch.PatentSearchArgs"/> containing the search arguments</param>

        /// <exception cref="Exception">if an error occurs during the search</exception>

        public void SearchAsync(PatentSearchArgs args)

        {

            base.SearchAsync(args);

        }



        /// <summary>

        /// This event is raised when the search is complete and the results

        /// are ready to be returned to the client.

        /// </summary>

        public event EventHandler<PatentSearchEventArgs> SearchComplete;



        /// <summary>

        /// This event is raised when the search fails for some reason. The event

        /// arguments Ex property will reference the exception.

        /// </summary>

        public event EventHandler<PatentSearchEventArgs> SearchFailed;



        /// <summary>

        /// This event is raised when key steps in the search process are

        /// completed. See the SearchStatus enumeration for possible values 

        /// for the PatentSearchEventArgs.Status parameter.

        /// <seealso cref="GSearch.SearchStatus"/>

        /// </summary>

        public event EventHandler<PatentSearchEventArgs> SearchProgressChanged;



        /// <summary>

        /// Returns a System.String containing a complete uri for the patent

        /// search service

        /// </summary>

        public override string ServiceURI

        {

            get { return base.ServiceURI + PatentResources.ServiceURI; }

        }



        /// <summary>

        /// Called by GSearchCore to raise the SearchComplete event

        /// </summary>

        /// <param name="e"><see cref="SearchEventArgs"/> containing 

        /// information about the event</param>

        protected override void OnSearchComplete(SearchEventArgs e)

        {

            EventHandler<PatentSearchEventArgs> ev = SearchComplete;

            if (null != ev)

            {

                PatentSearchEventArgs ie = new PatentSearchEventArgs(e);

                ev(this, ie);

            }

        }



        /// <summary>

        /// Called by GSearchCore to raise the SearchFailed event

        /// </summary>

        /// <param name="e"><see cref="SearchEventArgs"/> containing 

        /// information about the event</param>

        protected override void OnSearchFailed(SearchEventArgs e)

        {

            EventHandler<PatentSearchEventArgs> ev = SearchFailed;

            if (null != ev)

            {

                PatentSearchEventArgs ie = new PatentSearchEventArgs(e);

                ev(this, ie);

            }

        }



        /// <summary>

        /// Called by GSearchCore to raise the SearchProgressChanged event

        /// </summary>

        /// <param name="e"><see cref="SearchEventArgs"/> containing 

        /// information about the event</param>

        protected override void OnSearchProgressChanged(SearchEventArgs e)

        {

            EventHandler<PatentSearchEventArgs> ev = SearchProgressChanged;

            if (null != ev)

            {

                PatentSearchEventArgs ie = new PatentSearchEventArgs(e);

                ev(this, ie);

            }

        }



        /// <summary>

        /// Deserialize is called from the base when the search returns a valid

        /// result stream, it refers the call to the base class DeserializeImpl

        /// which actually does the work of deserialization.

        /// </summary>

        /// <param name="result">Stream result passed from the base class</param>

        /// <returns>Instance of <see cref="GSearch.GPatentResponse"/> as GResponse</returns>

        protected override GResponse Deserialize(System.IO.Stream result)

        {

            return DeserializeImpl<GPatentResponse>(result);

        }

    }

}