Module: EveXml

This library exposes all of CCPs XML API calls through an easy to use API, using common .NET and C# conventions. It uses a structure similar to how the API URIs are structured. See [APIv2] (http://wiki.eve-id.net/APIv2_Page_Index) for a reference. The basic structure is as follows:

• CharacterKey, CorporationKey and ApiKey exposes requests prefixed with /account/.
• Character exposes all requests prefixed with /char/.
• Corporation exposes all requests prefixed with /corp/.
• Map exposes all requests prefixed with /map/.
• Image exposes all requests to image.eveonline.com.
• Eve exposes all other API requests.

Requests

All basic functionality can be reached through a static facade class, EveOnlineApi. However, all methods and properties available in this class, can also be accessed by instantiating the respective classes using the new operator.

Basic

Eve, Map and Image do not require authentication, and can be accessed directly.

var result = EveXml.Map.GetFactionWarSystems();

Keys

The library has 3 different key classes, CharacterKey, CorporationKey and ApiKey. These represent actual Eve Online API keys, and are required to access any part of the API that requires authentication. The ApiKey can be used as a general key to access endpoints in the /account/ path, if you do not know which type of Key you have in advance.

ApiKey key = EveXml.CreateApiKey(id, vcode);
CharacterKey charKey = EveXml.CreateCharacterKey(id, vcode);
CorporationKey corpKey = EveXml.CreateCorporationKey(id, vcode);

All keys have a few properties in common, such as KeyType, ExpiryDate and AccessMask. These properties will be lazily loaded, synchronously, the first time they are accessed. After one of them have been accessed once, they will be stored in the object. You can also load them explicitly by calling Init(), or asynchronously by calling InitAsync(). CharacterKey and CorporationKey also have additional properties, Characters and Corporation, that are also lazily loaded in the same fashion. You can safely call Init() or InitAsync() repeatedly, if the object is already initialized it will return immediately.

key.Init(); // loads all properties, sync
await otherKey.InitAsync(); // loads all properties, async
int mask = corpKey.AccessMask(); // internally uses Init() to load all properties
var newkey = EveOnlineApi.CreateApiKey(id, vcode).Init(); // Init() and InitAsync() returns this, so it can be chained.

You can delete the stored data from keys by calling Reset(), which will remove any stored data, and any calls to Init(), InitAsync() or a lazily loaded property will cause a new request for the data, from the API or cache.

key.Reset(); // resets all properties, and IsInitialized is set to false

EveLib also provides a method to detect and return the actual type of key, which you can then cast to the real type. This method preserves any initialization data within the key.

var key = new ApiKey(keyId, vCode); // A user gave me some key info, and I have no idea if its for a char or corp
if (key.KeyType == ApiKeyType.Character) { // This lazily loads the KeyType and all other properties, from the API
    CharacterKey cKey = (CharacterKey)key.GetActualKey();
    // do work with your character key.
}

Using any key, you can access all /account/* paths (note: Only CharacterKey provides GetAccountInfo()):

EveXmlResponse<ApiKeyInfo> result = key.GetApiKeyInfo();

Character and Corporation

Character and Corporation classes provide access to endpoints in the /char/ and /corp/ paths respectively. There are mainly two ways to instantiate the Character and Corporation classes.

You can create a new object directly

Character character = EveXml.CreateNewCharacter(keyId, vCode, characterId); // using the static class
Corporation corporation = new Corporation(keyId, vCode, corporationId); // or using new

Or you can get them from an existing key

Character character = characterKey.Characters.Single(c => c.CharacterId == characterId); // key.Characters is a list of all characters this key can access
Character character = characterKey.Characters.Single(c => c.CharacterName == "MyName"); // find by name, or any other property
Corporation corporation = corporationKey.Corporation; // corp keys can only access a single corporation

The difference is, when creating an object directly, you will not know for sure whether the KeyID, vCode, and entityID is valid until you try to request data from API. Secondly, when creating it directly, it's properties will not be initialized. If you access objects through a key, all properties in both Character and Corporation objects will be pre-initialized with data from the key, at the cost of one call to the ApiKeyInfo endpoint.

Character and Corporation objects are initialized the same ways keys are, using Init(), InitAsync() or by accessing a property. You can also call Reset() to reset all data.

Responses

All API calls return results in the form of EveXmlResponse<T> objects, where T is the specific type of response. These objects reflect the structure of the actual XML responses, with a few exceptions. All properties have been renamed in compliance with C# naming conventions, eg. 'characterID' is converted to CharacterId. Also, some properties have been renamed for clarity and consistency, where most changes are extensions of the original names.

Every XML response has a Version, CachedUntil and Result. Result is of type T, and contains all request specific data.

    EveXmlResponse<ServerStatus> data = EveXml.Eve.GetServerStatus();
    int players = data.Result.PlayersOnline;

Exceptions

All calls to the Eve Online API can throw EveXmlException, which inherits from EveLibWebException. This additionaly exposes Message and ErrorCode, as returned by the API.