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