Bugzilla/IProxy.cs

Go to the documentation of this file.
00001 /* Bugzilla C# Proxy Library
00002    Copyright (C) 2006, Dansk BiblioteksCenter A/S
00003    Mads Bondo Dydensborg, <mbd@dbc.dk>
00004    
00005    This library is free software; you can redistribute it and/or
00006    modify it under the terms of the GNU Lesser General Public
00007    License as published by the Free Software Foundation; either
00008    version 2.1 of the License, or (at your option) any later version.
00009    
00010    This library is distributed in the hope that it will be useful,
00011    but WITHOUT ANY WARRANTY; without even the implied warranty of
00012    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013    Lesser General Public License for more details.
00014    
00015    You should have received a copy of the GNU Lesser General Public
00016    License along with this library; if not, write to the Free Software
00017    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
00018 */
00019 
00020 /*! \file
00021   \brief Definition of the methods supported by the Bugzilla WebService module.
00022   
00023   The definitions are used by the xml-rpc.net framework. User should
00024   use the IServer interface in the Bugzilla namespace instead.
00025 
00026   The purpose of this file is to define the proxy interface for use
00027   by xml-rpc. The xml-rpc interface of bugzilla is in essence a flat
00028   interface of functions, with names suggesting some kind of
00029   coherence between the different functions.
00030 
00031   Bugzilla's authentication system is based on cookies. This can be
00032   handled by the xml-rpc.net system. In order to make it as easy as
00033   possibly, all interface functions are attached to the same proxy.
00034   At the C# interface level, functions are named following C# sharp
00035   standard. The XmlRpcMethod attribute before each function tells
00036   which bugzilla RPC method is actually called by the interface.
00037 
00038   The standard of the %Bugzilla webservice is to have functions that
00039   takes parameters use a struct (perl:hash) and values returned, also
00040   return a struct (or nothing). In this interface this is organized by
00041   having each function (that takes a parameter) take a struct called
00042   param, of a type that is named after the function. Return types are
00043   likewise named after the method. So, e.g. "Login" uses a parameter
00044   type called "LoginParam", and returns a type called LoginResult.
00045   The meaning of these parameter and result types are described using
00046   C# inline docs in the actual structs.
00047 */
00048 
00049 using CookComputing.XmlRpc;
00050 using System;
00051 
00052 namespace Bugzproxy {
00053   using ProxyStructs;
00054 
00055   namespace ProxyStructs {
00056 
00057     //////////////////////////////////////////////////////////////////////
00058     // Version and timezone
00059 
00060     /// <summary>Result for call to <see cref="IProxy.GetVersion"/>.</summary>
00061     public struct GetVersionResult {
00062       /// <summary>The version of the server, as a string</summary>
00063       public string version;
00064     }
00065 
00066     /// <summary>Result for call to <see cref="IProxy.GetTimezone"/></summary>
00067     public struct GetTimezoneResult {
00068       /// <summary>The timezone information as a string, in RFC 2822 format</summary>
00069       [XmlRpcMember("timezone")]
00070       public string timeZone;
00071     }
00072 
00073     //////////////////////////////////////////////////////////////////////
00074     // Login handling
00075 
00076     /// <summary>Parameter struct for the <see cref="IProxy.Login"/> method</summary>
00077     public struct LoginParam {
00078       /// <summary>The user's login e-mail</summary>
00079       public string login;
00080       /// <summary>The user's password</summary>
00081       public string password;
00082       /// <summary>If the bugzilla server allow cookie session management, 
00083       /// then this option determines if the cookies issued by the server 
00084       /// can survive between sessions</summary>
00085       [XmlRpcMissingMapping(MappingAction.Ignore)]
00086       public bool? remember;
00087     }
00088     /// <summary>Parameter struct for the result of the <see cref="IProxy.Login"/>
00089     /// method</summary>
00090     public struct LoginResult {
00091       /// <summary>The numeric id of the user upon successful login</summary>
00092       public int id;
00093     }
00094 
00095 
00096     //////////////////////////////////////////////////////////////////////
00097     // Product handling
00098 
00099     /// <summary>A list of product ids. This is used in several methods, 
00100     /// both as a param and as a result type</summary>
00101     public struct ProductIds {
00102       /// <summary>Array of product ids</summary>
00103       public int[] ids;
00104     }
00105 
00106     /// <summary>Information about a single product.</summary>
00107     public struct ProductInfo {
00108       /// <summary>Internal information from the server about the product. 
00109       /// This can and will change frequently</summary>
00110       public XmlRpcStruct internals;
00111       /// <summary>Product nummeric id</summary>
00112       public int id;
00113       /// <summary>Product name</summary>
00114       public string name;
00115       /// <summary>Product description</summary>
00116       public string description;
00117     }
00118 
00119     /// <summary>A list of Products</summary>
00120     public struct GetProductsResult {
00121       /// <summary>Array of Products</summary>
00122       public ProductInfo[] products;
00123     }
00124 
00125     //////////////////////////////////////////////////////////////////////
00126     // Bug handling
00127 
00128     /// <summary>A list of bug ids. This is used in several functions, 
00129     /// both as a param and as a result type</summary>
00130     public struct BugIds {
00131       /// <summary>Array of bug ids</summary>
00132       public int[] ids;
00133     }
00134 
00135     /// <summary>Information about a single bug.</summary>
00136     public struct BugInfo {
00137       /// <summary>Internal information from the server about the bug. 
00138       /// This can and will change frequently</summary>
00139       public XmlRpcStruct internals;
00140       /// <summary>Bug nummeric id</summary>
00141       public int id;
00142       /// <summary>Bug alias (empty string if no aliases)</summary>
00143       public string alias;
00144       /// <summary>Bug summary</summary>
00145       public string summary;
00146       /// <summary>Time/date when bug was created</summary>
00147       [XmlRpcMember("creation_time")]
00148       public DateTime created;
00149       /// <summary>Time/date when bug was last changed</summary>
00150       [XmlRpcMember("last_change_time")]
00151       public DateTime changed;
00152     }
00153 
00154     /// <summary>A list of Bugs</summary>
00155     public struct GetBugsResult {
00156       /// <summary>Array of Bugs</summary>
00157       public BugInfo[] bugs;
00158     }
00159 
00160     /// <summary>Information needed to create a bug</summary>
00161     public struct CreateBugParam {
00162       /// <summary>Name of product to create bug against</summary>
00163       public string product;
00164       /// <summary>Name of component to create bug against</summary>
00165       public string component;
00166       /// <summary>Summary of bug</summary>
00167       public string summary;
00168       /// <summary>Version of product above, the version the bug was found in</summary>
00169       public string version;
00170       /// <summary>The initial description for this bug. Some %Bugzilla
00171       /// installations require this to not be blank.</summary>
00172       [XmlRpcMissingMapping(MappingAction.Ignore)]
00173       public string description;
00174       /// <summary>The operating system the bug was discovered
00175       /// on. Some %Bugzilla installations require this to not be
00176       /// blank.</summary>
00177       [XmlRpcMissingMapping(MappingAction.Ignore)]
00178       [XmlRpcMember("op_sys")]
00179       public string operatingSystem;
00180       /// <summary>What type of hardware the bug was experienced
00181       /// on. Some %Bugzilla installations require this to not be
00182       /// blank.</summary>
00183       [XmlRpcMissingMapping(MappingAction.Ignore)]
00184       public string platform;
00185       /// <summary>What order the bug will be fixed in by the
00186       /// developer, compared to the developers other bugs. Some
00187       /// %Bugzilla installations require this to not be
00188       /// blank. </summary>
00189       [XmlRpcMissingMapping(MappingAction.Ignore)]
00190       public string priority;
00191       /// <summary>How severe the bug is. Some %Bugzilla installations
00192       /// require this to not be blank. </summary>
00193       [XmlRpcMissingMapping(MappingAction.Ignore)]
00194       public string severity;
00195       /// <summary>A brief alias for the bug that can be used instead
00196       /// of a bug number when accessing this bug. Must be unique in
00197       /// all of this %Bugzilla.</summary>
00198       [XmlRpcMissingMapping(MappingAction.Ignore)]
00199       public string alias;
00200       /// <summary>A user to assign this bug to, if you dont want it
00201       /// to be assigned to the component owner.</summary>
00202       [XmlRpcMissingMapping(MappingAction.Ignore)]
00203       [XmlRpcMember("assigned_to")]
00204       public string assignedTo;
00205       /// <summary>An array of usernames to CC on this bug.</summary>
00206       [XmlRpcMissingMapping(MappingAction.Ignore)]
00207       public string[] cc;
00208       /// <summary>If this installation has QA Contacts enabled, you
00209       /// can set the QA Contact here if you don't want to use the
00210       /// component's default QA Contact.</summary>
00211       [XmlRpcMissingMapping(MappingAction.Ignore)]
00212       [XmlRpcMember("qa_contact")]
00213       public string qaContact;
00214       /// <summary>The status that this bug should start out as. Note
00215       /// that only certain statuses can be set on bug creation.</summary>
00216       [XmlRpcMissingMapping(MappingAction.Ignore)]
00217       public string status;
00218       /// <summary>A valid target milestone for this product.</summary>
00219       [XmlRpcMissingMapping(MappingAction.Ignore)]
00220       [XmlRpcMember("target_milestone")]
00221       public string targetMilestone;
00222     }
00223 
00224     /// <summary>Result of call to <see cref="IProxy.CreateBug"/></summary>
00225     public struct CreateBugResult {
00226       /// <summary>The id of the newly created bug</summary>
00227       public int id;
00228     }
00229 
00230     // Legal values for fields of a bug
00231     /// <summary>Parameter for <see cref="IProxy.GetLegalValuesForBugField"/> call.</summary>
00232     public struct GetLegalValuesForBugFieldParam {
00233       /// <summary>Which field to query for</summary>
00234       public string field;
00235       /// <summary>If the field is product specific, which product then</summary>
00236       [XmlRpcMember("product_id")]
00237       public int productId;
00238     }
00239 
00240     /// <summary>Result of call to <see cref="IProxy.GetLegalValuesForBugField"/>
00241     /// </summary>
00242     public struct GetLegalValuesForBugFieldResult {
00243       /// <summary>Array of values</summary>
00244       public string[] values;
00245     }
00246 
00247     /// <summary>Parameter for <see cref="IProxy.AppendComment"/> call</summary>
00248     public struct AppendCommentParam {
00249       /// <summary>The id of the bug</summary>
00250       public int id;
00251       /// <summary>The actual comment to append</summary>
00252       public string comment;
00253       /// <summary>Whether or not this is a private comment.</summary>
00254       /// <remarks>This is ignored if you are not in the <i>insidergroup</i>.
00255       /// </remarks>
00256       // Note, must use renaming, as "private" is reserved in C#.
00257       [XmlRpcMissingMapping(MappingAction.Ignore)]
00258       [XmlRpcMember("private")]
00259       public bool? isPrivate;
00260       /// <summary>The worktime of this comment.</summary>
00261       [XmlRpcMissingMapping(MappingAction.Ignore)]
00262       [XmlRpcMember("work_time")]
00263       public double? workTime;
00264     }
00265 
00266     /// <summary>Parameter for call to <see cref="IProxy.SetBugResolution"/></summary>
00267     public struct SetBugResolutionParam {
00268       /// <summary>The id of the bug</summary>
00269       [XmlRpcMember("bug_id")]
00270       public int bugId;
00271       /// <summary>The actual resolution to set. Should be legal.</summary>
00272       public string resolution;
00273     }
00274 
00275   } // namespace ProxyStructs
00276 
00277   /// <summary>The interface for use by the xml-rpc.net framework.</summary>
00278   /// <remarks>The interface methods translate
00279   /// into other method names at the server end, as we are using
00280   /// .NET name styling. It also puts all methods in the same
00281   /// interface. This may change. Users are not expected to use this
00282   /// interface directly.</remarks>
00283   public interface IProxy : IXmlRpcProxy {
00284 
00285     //////////////////////////////////////////////////////////////////////
00286     // Server related / general methods
00287     //////////////////////////////////////////////////////////////////////
00288 
00289     /*! \name General Methods */
00290     //@{
00291 
00292     //////////////////////////////////////////////////////////////////////
00293     /// <summary>Get the version of the server</summary>
00294     /// <returns>The version of the server as a string</returns>
00295     [XmlRpcMethod("Bugzilla.version")]
00296     GetVersionResult GetVersion();
00297 
00298     //////////////////////////////////////////////////////////////////////
00299     /// <summary>Get the timezone of the server</summary>
00300     /// <returns>The timezone information as a string, in RFC 2822 format</returns>
00301     [XmlRpcMethod("Bugzilla.timezone")]
00302     GetTimezoneResult GetTimezone();
00303     //@}
00304 
00305     /*! \name Login/out */
00306     //@{
00307     //////////////////////////////////////////////////////////////////////
00308     /// <summary>Login to the server</summary> 
00309     /// <param name="param">Login, password and optional remember value</param>
00310     /// <returns>If successful, the user's numeric id</returns>
00311     [XmlRpcMethod("User.login")]
00312     LoginResult Login(LoginParam param);
00313 
00314     //////////////////////////////////////////////////////////////////////
00315     /// <summary>Logout of the server</summary>
00316     [XmlRpcMethod("User.logout")]
00317     void Logout();
00318     //@}
00319 
00320     //////////////////////////////////////////////////////////////////////
00321     // Product related methods
00322     //////////////////////////////////////////////////////////////////////
00323     /*! \name Product Related Methods */
00324     //@{
00325     //////////////////////////////////////////////////////////////////////
00326     /// <summary>Get a list of the products (ids) that the user can
00327     /// search against.</summary>
00328     /// <returns>A list of product ids</returns>
00329     [XmlRpcMethod("Product.get_selectable_products")]
00330     ProductIds GetSelectableProducts();
00331 
00332     //////////////////////////////////////////////////////////////////////
00333     /// <summary>Get a list of the products (ids) that the user can
00334     /// post bugs against.</summary>
00335     /// <returns>A list of product ids</returns>
00336     [XmlRpcMethod("Product.get_enterable_products")]
00337     ProductIds GetEnterableProducts();
00338 
00339     //////////////////////////////////////////////////////////////////////
00340     /// <summary>Get a list of the products (ids) that the user can
00341     /// search or enter bug against.</summary>
00342     /// <returns>A list of product ids</returns>
00343     [XmlRpcMethod("Product.get_accessible_products")]
00344     ProductIds GetAccessibleProducts();
00345 
00346     //////////////////////////////////////////////////////////////////////
00347     /// <summary>Get a list of products from a list of ids</summary>
00348     /// <param name="param">A list of product ids</param>
00349     /// <returns>A list of products</returns>
00350     [XmlRpcMethod("Product.get_products")]
00351     GetProductsResult GetProducts(ProductIds param);
00352     //@}
00353 
00354     //////////////////////////////////////////////////////////////////////
00355     // Bug related methods
00356     //////////////////////////////////////////////////////////////////////
00357     /*! \name Bug Related Methods */
00358     //@{
00359 
00360     //////////////////////////////////////////////////////////////////////
00361     /// <summary>Create a new bug</summary>
00362     /// <param name="param">Various information about the new bug</param>
00363     /// <returns>The id of the newly created bug</returns>
00364     [XmlRpcMethod("Bug.create")]
00365     CreateBugResult CreateBug(CreateBugParam param);
00366 
00367     //////////////////////////////////////////////////////////////////////
00368     /// <summary>Get a list of bugs from a list of ids</summary>
00369     /// <param name="param">A list of bug ids</param>
00370     /// <returns>A list of bugs</returns>
00371     [XmlRpcMethod("Bug.get_bugs")]
00372     GetBugsResult GetBugs(BugIds param);
00373 
00374     //////////////////////////////////////////////////////////////////////
00375     /// <summary>Get a list of legal values for a field in a bug</summary>
00376     /// <param name="param">Which field, possibly product</param>
00377     /// <returns>The legal values for the field</returns>
00378     [XmlRpcMethod("Bug.legal_values")]
00379     GetLegalValuesForBugFieldResult GetLegalValuesForBugField(GetLegalValuesForBugFieldParam param);
00380 
00381     //@}
00382 
00383     /*! \name Experimental Methods
00384       These are here as part of the development of patches, etc. */
00385     //@{
00386 
00387     //////////////////////////////////////////////////////////////////////
00388     /// <summary>Append a comment</summary>
00389     /// <remarks>Works with Bugzilla trunk (3.1.2+) only</remarks>
00390     /// <param name="param">Bug id, comment, etc</param>
00391     [XmlRpcMethod("Bug.add_comment")]
00392     void AppendComment(AppendCommentParam param);
00393 
00394     //////////////////////////////////////////////////////////////////////
00395     /// <summary>Change the resolution of a bug</summary>
00396     /// <remarks>This requires an unpublished patch</remarks>
00397     /// <param name="param">Bug id and resolution</param>
00398     [XmlRpcMethod("Bug.set_resolution")]
00399     string SetBugResolution(SetBugResolutionParam param);
00400 
00401     //@}
00402   }
00403 } // namespace

Generated on Thu Jan 17 07:31:46 2008 for BugzillaProxy by  doxygen 1.5.4