Server Class Reference

Collaboration diagram for Server:

Collaboration graph
[legend]

List of all members.


Detailed Description

This class encapsulates a Bugzilla server.

Access is done through http/xmlrpc.

Properties reflect settings that will not cause network traffic, while methods typically involves the server on the other end.

Definition at line 62 of file Server.cs.


Authentication Handling

Methods to log in/out, and store/set credentials.

CookieCollection Cookies [get, set]
 Get or set the cookies that are currently used as credentials.
int Login (string username, string password, bool remember)
 Login to the server.
void Logout ()
 Logout of the server.
void WriteCookies (Stream stream)
 Write the currently used cookies to a stream.
void ReadCookies (Stream stream)
 Read cookies from a stream.

Bug Access

Methods to get information about the bugs that the server knows.

Note: There is currently no search support in the Bugzilla WebService. When this is implemented, the search facilities should complement these services nicely.

As for products, a user may not have read/write access to all bugs.

const string OperatingSystem = "operatingSystem"
 Represents the op_sys field of a bug.
const string AssignedTo = "assignedTo"
 Represetns the assigned_to field of a bug.
const string QaContact = "qaContact"
 Represents the qa_contact field of a bug.
const string TargetMilestone = "targetMilestone"
 Represents the target_milestone field of a bug.
Bug[] GetBugs (int[] ids)
 Get a list of bugs.
Bug GetBug (int id)
 Get a bug.
string[] GetLegalFieldValues (string fieldName)
 Get a list of legal values for a non-product specific bug field.

Public Member Functions

Constructors


 Server (string hostname, uint port, string path, bool ssl, TextWriter traceWriter)
 Initialize a new instance of the Server class with the specified parameters.
 Server (string hostname, uint port, string path)
 Initialize a new instance of the Server class with the specified host name, port and path.
 Server (string hostname, uint port, bool ssl)
 Initialize a new instance of the Server class with the specified parameters.
 Server (string hostname, uint port)
 Initialize a new instance of the Server class with the specified host name and port number.
 Server (string hostname, string path)
 Initialize a new instance of the Server class with the specified host name and path.
 Server (string hostname, bool ssl)
 Initialize a new instance of the Server class with the specified host name and protocol.
 Server (string hostname)
 Initialize a new instance of the Server class with the specified host name.
 Server ()
 Initialize a new instance of the Server class.
General Methods
Methods to get information about the server, and log in/out.

string GetVersion ()
 Get the version of the server.
string GetTimezone ()
 Get the server's time zone.
Product Access
Methods to get information about the products that the server knows

A user may not have access to all products. A user may have access to search and view bugs from some products, and additionally, to enter bugs against some other products. Methods for this are exposed here. Additionally, general methods to retrieve one or more bugs are made avaiable as well.

int[] GetSelectableProductIds ()
 Get a list of the products a user can search.
int[] GetEnterableProductIds ()
 Get a list of the products a user can file bugs against.
int[] GetAccessibleProductIds ()
 Get a list of the products an user can search or file bugs against.
Product[] GetProducts (int[] ids)
 Get a list of existing products.
Product GetProduct (int id)
 Get a single existing product.
Experimental
These methods are experimental, and will change/move, as the API stabilizes.

int CreateBug (string product, string component, string summary, string description)
 Create a bug - experimental.
string SetBugResolution (int bugId, string resolution)
 Change the resolution of a bug.

Properties

bool PreAuthenticate [get, set]
 Get or set PreAuthenticate.
ICredentials Credentials [get, set]
 Get or set credentials.
string Hostname [get, set]
 Get or set the server's host name.
uint Port [get, set]
 Get or set the port of the web server.
string Path [get, set]
 Get or set the path.
bool LoggedIn [get, set]
 Get the login status.
TextWriter TraceWriter [get, set]
 Get or set a TextWriter for debug traces.

Classes

class  TextWriterTracer
 Trace data sent and received using the XML-RPC framework.

Constructor & Destructor Documentation

Server ( string  hostname,
uint  port,
string  path,
bool  ssl,
TextWriter  traceWriter 
) [inline]

Initialize a new instance of the Server class with the specified parameters.

Parameters:
hostname The name of the server to use
port The port to use
path The path to use
ssl If true, use https for connections, otherwise use http
traceWriter A TextWriter instance to trace to
The path paremeter denotes the path to Bugzilla on the server. E.g. if Bugzilla is installed on http://example.com/bugs, then path is "bugs".

Definition at line 213 of file Server.cs.

References Server::LoggedIn.

Server ( string  hostname,
uint  port,
string  path 
) [inline]

Initialize a new instance of the Server class with the specified host name, port and path.

This constructs with a null TraceWriter, empty Path, and http as protocol (scheme).

Parameters:
hostname The name of the server to use
port The port to use
path The path to use

Definition at line 235 of file Server.cs.

Server ( string  hostname,
uint  port,
bool  ssl 
) [inline]

Initialize a new instance of the Server class with the specified parameters.

This constructs with a null TraceWriter and empty Path.

Parameters:
hostname The name of the server to use
port The port to use
ssl If true, use https for connections, otherwise use http

Definition at line 247 of file Server.cs.

Server ( string  hostname,
uint  port 
) [inline]

Initialize a new instance of the Server class with the specified host name and port number.

This constructs with a null TraceWriter, empty Path, and http as protocol (scheme).

Parameters:
hostname The name of the server to use
port The port to use

Definition at line 258 of file Server.cs.

Server ( string  hostname,
string  path 
) [inline]

Initialize a new instance of the Server class with the specified host name and path.

This constructs with a null TraceWriter at port 80, with empty Path and http as protocol (scheme)

Parameters:
hostname The name of the server to use
path The path to use

Definition at line 269 of file Server.cs.

Server ( string  hostname,
bool  ssl 
) [inline]

Initialize a new instance of the Server class with the specified host name and protocol.

This constructs with a null TraceWriter, and empty Path. Depending on the setting of ssl, the port will be either 80 (false) or 443 (true).

Parameters:
hostname The name of the server to use
ssl If true, use https for connections at port 443, otherwise use http at port 80.

Definition at line 282 of file Server.cs.

Server ( string  hostname  )  [inline]

Initialize a new instance of the Server class with the specified host name.

This constructs using port 80, with an empty Path, with a null TraceWriter, and using http.

Parameters:
hostname The name of the server to use

Definition at line 292 of file Server.cs.

Server (  )  [inline]

Initialize a new instance of the Server class.

This constructs using an empty Hostname, an empty Path, port 80, using http, and with a null TraceWriter.

Definition at line 303 of file Server.cs.


Member Function Documentation

string GetVersion (  )  [inline]

Get the version of the server.

This requires that at least the Hostname has been set. GetVersion can be called without beeing logged in to the Bugzilla server.

Exceptions:
InvalidOperationException This exception will be thrown if Hostname is empty

Definition at line 427 of file Server.cs.

References IProxy::GetVersion(), Server::Hostname, and GetVersionResult::version.

string GetTimezone (  )  [inline]

Get the server's time zone.

This returns the servers timezone as a string in (+/-)XXXX (RFC 2822) format. All time/dates returned from the server will be in this time zone.

Returns:
The server's time zone as a string

Definition at line 439 of file Server.cs.

References IProxy::GetTimezone(), Server::Hostname, and GetTimezoneResult::timeZone.

int Login ( string  username,
string  password,
bool  remember 
) [inline]

Login to the server.

Most servers require you to log in before you can retrieve information other than the version, let alone work with bugs, products or components.

Currently, the remember parameter is ignored by Bugzproxy.

Parameters:
username The Bugzilla username to use
password The Bugzilla password to use
remember Same meaning as the remember checkbox of the web interface.
Returns:
The server's internal ID number for this user.
Exceptions:
InvalidOperationException This exception will be thrown if trying to login, while already logged in.

Definition at line 475 of file Server.cs.

References LoginResult::id, Server::LoggedIn, IProxy::Login(), LoginParam::login, and LoginParam::password.

void Logout (  )  [inline]

Logout of the server.

You must be logged in to call this function. This will invalidate the cookies set by Bugzilla.

Exceptions:
InvalidOperationException This exception will be thrown if trying to logout, without being logged in.

Definition at line 493 of file Server.cs.

References Server::LoggedIn, and IProxy::Logout().

void WriteCookies ( Stream  stream  )  [inline]

Write the currently used cookies to a stream.

Parameters:
stream The stream to write the cookies to.
By obtaining the cookies, you can store them somewhere, and use them instead of a login during a new session.
Exceptions:
InvalidOperationException This exception will be thrown if trying to set the cookies, without being logged in.

Definition at line 535 of file Server.cs.

References Server::Cookies.

void ReadCookies ( Stream  stream  )  [inline]

Read cookies from a stream.

Parameters:
stream The stream to read the cookies from.

By calling this method with a stored set of cookies, you do not need to perform a login.

This method expects the stream to contain the cookies as they are written by WriteCookies.

Exceptions:
InvalidOperationException This exception will be thrown if trying to get the Cookies, while being logged in

Definition at line 552 of file Server.cs.

References Server::Cookies.

int [] GetSelectableProductIds (  )  [inline]

Get a list of the products a user can search.

Returns:
List of product ids that the user can search against

Definition at line 575 of file Server.cs.

References IProxy::GetSelectableProducts(), and ProductIds::ids.

int [] GetEnterableProductIds (  )  [inline]

Get a list of the products a user can file bugs against.

Returns:
List of product ids that the user can file bugs against

Definition at line 581 of file Server.cs.

References IProxy::GetEnterableProducts(), and ProductIds::ids.

int [] GetAccessibleProductIds (  )  [inline]

Get a list of the products an user can search or file bugs against.

This is effectively a union of GetSelectableProductIds and GetEnterableProductIds.

Returns:
List of product ids that the user can search or file bugs against

Definition at line 589 of file Server.cs.

References IProxy::GetAccessibleProducts(), and ProductIds::ids.

Product [] GetProducts ( int[]  ids  )  [inline]

Get a list of existing products.

This returns an array of products, matching the ids supplied as argument. Note, however, that if the user has specified an id for a product that the user for some reason can not access, this is silently ignored.

Parameters:
ids List of product ids
Returns:
List of products

Definition at line 603 of file Server.cs.

References IProxy::GetProducts(), ProductIds::ids, and GetProductsResult::products.

Referenced by Server::GetProduct().

Product GetProduct ( int  id  )  [inline]

Get a single existing product.

This returns a single existing product from the id

Parameters:
id The id of the product to get
Returns:
A Product object.
Exceptions:
ArgumentOutOfRangeException This exception will be thrown, if the id does not exists, or can not be accessed

Definition at line 620 of file Server.cs.

References Server::GetProducts().

Bug [] GetBugs ( int[]  ids  )  [inline]

Get a list of bugs.

This returns an array of bugs, matching the ids supplied as arguments. Note, that if the user has specified an id for a bug that does not exist, or that the user can not access (read), an exception will be thrown. This is different from GetProducts.

Parameters:
ids List of bug ids
Returns:
Array of Bug objects

Todo:
Document exception, when known.

Definition at line 657 of file Server.cs.

References GetBugsResult::bugs, IProxy::GetBugs(), and BugIds::ids.

Referenced by Server::GetBug().

Bug GetBug ( int  id  )  [inline]

Get a bug.

This return a single existing bug, from the id

Parameters:
id The id of a bug
Returns:
A bug
Exceptions:
ArgumentOutOfRangeException This exception will be thrown, if the id does not exists, or can not be accessed

Definition at line 677 of file Server.cs.

References Server::GetBugs().

Referenced by Product::CreateBug().

string [] GetLegalFieldValues ( string  fieldName  )  [inline]

Get a list of legal values for a non-product specific bug field.

This can be used to retrieve a list of legal values for non-product specific fields of a bug, such as status, severity, and so on. When applicable, you should prefer using one of OperatingSystem, AssignedTo, QaContact or TargetMilestone. For other fields, including your own custom fields, you may use the Bugzilla original naming (such as op_sys). Note, that in order to retrieve values for product specific fields (such as component), you must use the Product.GetLegalFieldValues method.

Returns:
A list of legal values for the field
Parameters:
fieldName The name of a field.

Definition at line 725 of file Server.cs.

Referenced by Product::GetLegalFieldValues().

int CreateBug ( string  product,
string  component,
string  summary,
string  description 
) [inline]

Create a bug - experimental.

Parameters:
product Product name
component Component name
summary Bug summary
description Bug initial description
Returns:
the number -1.
This method is obsulete and does nothing. You should use Product.CreateBug instead.

Definition at line 771 of file Server.cs.

string SetBugResolution ( int  bugId,
string  resolution 
) [inline]

Change the resolution of a bug.

Parameters:
bugId The Bug number
resolution The new resolution
Returns:
?
This method is not supported by current versions of Bugzilla, and will require a custom patch to work.

Definition at line 784 of file Server.cs.

References SetBugResolutionParam::bugId, SetBugResolutionParam::resolution, and IProxy::SetBugResolution().


Member Data Documentation

const string OperatingSystem = "operatingSystem"

Represents the op_sys field of a bug.

See GetLegalFieldValues for details.

Definition at line 693 of file Server.cs.

const string AssignedTo = "assignedTo"

Represetns the assigned_to field of a bug.

See GetLegalFieldValues for details.

Definition at line 699 of file Server.cs.

const string QaContact = "qaContact"

Represents the qa_contact field of a bug.

See GetLegalFieldValues for details.

Definition at line 705 of file Server.cs.

const string TargetMilestone = "targetMilestone"

Represents the target_milestone field of a bug.

See GetLegalFieldValues for details.

Definition at line 711 of file Server.cs.


Property Documentation

bool PreAuthenticate [get, set]

Get or set PreAuthenticate.

true or false.

This property exposes the PreAuthenticate property of the underlying XML-RPC library, in case it may be of use to you.

Definition at line 151 of file Server.cs.

ICredentials Credentials [get, set]

Get or set credentials.

An ICredentials implementation.

This property exposes the Credentials property of the underlying XML-RPC library, in case it may be of use to you.

Definition at line 166 of file Server.cs.

string Hostname [get, set]

Get or set the server's host name.

If you set it while logged in, an exception will be thrown

Exceptions:
InvalidOperationException This exception will be thrown if trying to set the host name while logged in.

Definition at line 330 of file Server.cs.

Referenced by Server::GetTimezone(), and Server::GetVersion().

uint Port [get, set]

Get or set the port of the web server.

If you set the port while logged in, an exception will be thrown. By default the port will be set to 80 for HTTP connections (the standard http port), and 443 for HTTPS connections.

Exceptions:
InvalidOperationException This exception will be thrown if trying to set the property while logged in.

Definition at line 349 of file Server.cs.

string Path [get, set]

Get or set the path.

Denotes the path to Bugzilla on the server. E.g. if Bugzilla is installed on http://example.com/bugs, then the path is "bugs".

If you set the path while logged in, an exception will be thrown. By default the path will be set to the empty string.

Exceptions:
System.InvalidOperationException This exception will be thrown if trying to set the property while logged in

Definition at line 371 of file Server.cs.

bool LoggedIn [get, set]

Get the login status.

If the user is logged in, returns true. Otherwise, return false.

Definition at line 387 of file Server.cs.

Referenced by Server::Login(), Server::Logout(), and Server::Server().

TextWriter TraceWriter [get, set]

Get or set a TextWriter for debug traces.

If set, the HTTP request and response will be written to this TextWriter

Definition at line 400 of file Server.cs.

CookieCollection Cookies [get, set]

Get or set the cookies that are currently used as credentials.

A CookieCollection object with the currently used credetials cookies.

By obtaining the cookies, you can store them somewhere, and use them instead of a login during a new session.

Exceptions:
InvalidOperationException This exception will be thrown if trying to set the cookies while logged in, or trying to get the cookies without beeing logged in.

Definition at line 510 of file Server.cs.

Referenced by Server::ReadCookies(), and Server::WriteCookies().


The documentation for this class was generated from the following file:
Generated on Thu Jan 17 07:31:46 2008 for BugzillaProxy by  doxygen 1.5.4