Server interface

From DKPLP Doc

Jump to: navigation, search

The server interface is an XML-RPC interface that allows the program to communicate with DKP server software. The interface specification lists a basic set of functions that have to be available via XML-RPC. Other programs can also use this interface to communicate with server software, for instance the EQDKP plugin can be used by other applications if they send XML-RPC calls to the dkplp/xmlrpc/dkprpc.php file.

If you're interested in making an plugin for some other server DKP software, but can't fulfill the specification, then please tell the development forum so that a new specification, which takes some limitations in mind, can be produced.

Specification

The following is the complete interface specification S7 .

Get available representations

External name: getAvailableRepresentations
Parameter count: zero
Return type: array<array<array<string>>>
Action: Gets the names of all the ways provided by the server to represent the different aspects of a day.

Return value

An array with four entries that each is an array in with two elements, both arrays of strings. Each element in the first of those two arrays contains unique identifiers used by the server to identify each representation. The second array contains the same number of elements as the first array and the element at the i:th position in the second array is a describing name for the unique identifier at position i in the first array.

Each array represents one aspect of the day that can be represented, the aspects are (in the same order as found in the array):

General apects of the day
The loot items
Reward intervals
Events
High participation bonus

Add day

External name: addDay
Parameter count: four
Return type: boolean
Action: Adds the day described by the parameters, representing it as specified by the parameters.

Parameters

Any array entries beyond the specified ones should be ignored. Additional parameters should be allowed but ignored.

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
array<string> - An array of unique identifiers (as given by Get representations) each corresponding to a way to represent the part of the day. The parts of the day are:
1. General apects of the day
2. The loot items
3. Reward intervals
4. Events
5. High participation bonus
array<array<mixed>> - An array describing the day that should be added, the array contains the following entries.
1. array<mixed> - An array containing general properties of the raid. It contains the following entries.
  1. i4 - The timestamp (seconds) describing the point in time when the raid started.
  2. array<string> - An array containing the names of everyone who has been present at some point during the day.
2. array<mixed> - An array containing entries that each describe one loot item dropped during the day, the entries are sorted chronologically ascending. Each entry is an array which contain the following entries.
  1. i4 - The timestamp (seconds) describing the point in time when the loot item was dropped.
  2. string - The name of the item that dropped.
  3. double - The price payed for the item (in DKP).
  4. string - The name of the person that bought the item.
3. array<mixed> - An array containing entries that each describe one reward interval during the day, the entries are sorted chronologically ascending. Each entry is an array which contains the following entries.
  1. i4 - The timestamp (seconds) describing the point in time when the reward interval began.
  2. i4 - The timestamp (seconds) describing the point in time when the reward interval ended.
  3. double - The number of DKP that should be rewarded to each participating member.
  4. array<string> - An array of strings, each contained string represents the name of one member that should be considered present during the reward interval.
  5. string - The raid name of the reward interval, may be emtpy.
  6. string - A note that should be displayed with the reward interval if possible, may be emtpy.
4. array<mixed> - An array containing entries that each describe one event present in the day, the entries are sorted chronologically ascending. Each entry is an array which contains the following entries.
  1. i4 - The timestamp describing the point in time when the event occurred.
  2. string - The name of the event.
  3. double - The number of DKP that should be rewarded to each participating member.
  4. array<string> - An array of strings, each contained string represents the name of one member that should be considered present during the event.
  5. string - A note describing the event, may be emtpy.
5. array<mixed> - An array that describes the high participation bonus, containing the following entries.
  1. double - The number of DKP that should be rewarded to each member with high participation. If this value is 0 then the server should avoid displaying a high participation bonus (as none exists) if possible.
  2. array<string> - An array of strings, each contained string represents the name of one member that should be considered to have participation.

Return value

True if the day was successfully added, false (or thrown error) otherwise.

Get members

External name: getMembers
Parameter count: three
Return type: array<string>
Action: Gets the names of all members contained on the server. Optionally they have to hold one of several specified ranks.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
array<i4> - An array where each element represents a unique identifier of the rank that a retrieved member has to hold. This parameter may optionally be ignored by the implementation.

Return value

An array in which each element should be a name. If no members match then an empty array should be returned.

Has read/write permissions

External name: hasRWPermission
Parameter count: two
Return type: boolean
Action: Checks if the specified user name and password combination has permission to read and write via the plugin. Please note that this does not act as a way for the program to check authenticity of the user before using the other functions. Every function that reads or writes from databases, or has any other sideffect that could be a security problem, should always perform an authentication on the server when called.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.

Return value

True if the provided user name and password combination has permission to use the interface's functions, false otherwise.

Get all ranks

External name: getAllRanks
Parameter count: two
Return type: array<array>
Action: Retrieves all member ranks defined by the server. This function is optional and the implementation may always return an empty array containing two empty arrays.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.

Return value

The returned array should contain two arrays. The first of the two arrays should contain integers (i4) that represent unique identifiers for ranks. The second of the two arrays should contain strings that represent names for said ranks. The two arrays should be ordered so that the identifier at index n in the first array is the unique identifier for the rank with the name located at index n in the second array.

Get specification number

External name: getSpecificationNumber
Parameter count: zero
Return type: string
Action: Retrieves the server's implemented interface's specification number.

Return value

A string with format Sn where n is a positive integer. The string should reflect the interface specification number of the currently implemented interface.

Add member

External name: addMember
Parameter count: three
Return type: void
Action: Registers a new member at the server. This function may be implemented so that it does nothing in case the server does not support registering members.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
string - The name of the member that should be registered.

Set configuration

External name: setConfig
Parameter count: three
Return type: void
Action: Stores the configuration specified in XML by the passed string. The configuration should be made available through the get configuration function.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
string - The configuration, in XML form, that should be uploaded.

Get configuration

External name: getConfig
Parameter count: zero
Return type: string
Action: Retrieves the most recently stored configuration that was sent via the set configuration function. The configuration should be sent back in its XML form (just as it was delivered).

Return value

An string of XML describing a DKP Log Parser configuration in its XML form.

Set completions

External name: setCompletions
Parameter count: three
Return type: void
Action: Stores the autocompletion database specified by the passed string in XML. The completions should be made available through the get completions function.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
string - The autocompletion database, in XML form, that should be uploaded.

Get completions

External name: getCompletions
Parameter count: zero
Return type: string
Action: Retrieves the most recently stored completions that was sent via the set completions function. The completions should be sent back in XML form (just as it was delivered).

Return value

An string of XML describing an autocompletion database in XML form.

Set member aliases

External name: setMemberAliases
Parameter count: three
Return type: void
Action: Stores the member aliases specified in XML by the passed string. The configuration should be made available through the get member aliases.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
string - The member aliases, in XML form, that should be uploaded.

Get member aliases

External name: getMemberAliases
Parameter count: zero
Return type: string
Action: Retrieves the most recently stored member aliases that were sent via the set member aliases function. The configuration should be sent back in its XML form (just as it was delivered).

Known implementations

EQDKP

A plugin is available for EQDKP. Installing it implements an interface into EQDKP that satisfies specification S7 . The interface can be accessed by sendomg XML-RPC calls to the dkplp/xmlrpc/dkprpc.php file.

Changelog

S7

Deprecated Add raid
Deprecated Add raid attendees
Deprecated Add loot item
Deprecated Add raid batch
Deprecated Add event
Added Get day
Added Get available representations

S6

Added Set member aliases.
Added Get member aliases.

S5

Added Add event.

S4

Added Add raid batch.
The types used have been reviewed and some variables that really ought to have been something else (for instance prices, which are doubles instead of string) have now been corrected. See the wiki diff for a complete list.

S3

Added Get specification number
Deprecated Get plugin version
New version numbering introduced in order to avoid confusion with the plugin versions. Previously the version numbering started at 1.2.2 and behaved like a program version. Now the interface specifications are simply labeled by Sn where n is an positive integer.

S2

Previously known as version 1.2.3 .

Added Set configuration.
Added Get configuration.
Added Set completions.
Added Get completions.

S1

Previosuly known as version 1.2.2 . The first public specification version.

Deprecated specifications

Add raid

Deprecated: As of S7 this function is deprecated.
External name: addRaid
Parameter count: six
Return type: i4
Action: Adds a raid to the server. The raid should have a specified name and reward. Optionally it should also have a specified time of addition and a specified note.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
string - The name that the raid should have.
string - The unix timestamp representing the point in time that the raid should display having been added at. This parameter may optionally be ignored by the implementation.
string - The text that should be displayed to describe the raid, e.g. as a small note. This parameter may optionally be ignored by the implementation.
double - The number of DKP that should be rewarded to participants of the raid.

Return value

An unique identifier connected to the raid that was just added. The identifier is then used when adding participants to the raid.

Add raid attendees

Deprecated: As of S7 this function is deprecated.
External name: addRaidAttendees
Parameter count: four
Return type: void
Action: Adds specified members to a raid which is associated with the specified unique identifier.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
i4 - The unique identifier that is connected to the raid to which the attendees should be added. This is the value returned by add raid.
array<string> - Each array element is a name of the persons that should be added. The persons do not have to be registered on the server. If unregistered persons are not allowed then all unregistered persons should be ignored, but the rest should still be processed.

Add loot item

Deprecated: As of S7 this function is deprecated.
External name: addLoot
Parameter count: seven
Return type: void
Action: Adds a loot item with the specified characteristics. Optionally the loot item is also associated with a raid which is connected to the specified unique identifier.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
string - The name that the item should have.
double - The number of DKP that the item should display as cost. This parameter may optionally be ignored by the implementation.
string - The name of the person that bought the item. The person do not have to be registered on the server. If unregistered persons are not allowed then requests containing unregistered persons may be ignored by the implementation.
i4 - The unique identifier that specifies the raid to which the item should be connected. This parameter may optionally be ignored by the implementation.
string - The unix timestamp representing the point in time that the item should display as time of purchase. This parameter may optionally be ignored by the implementation.

Add raid batch

Deprecated: As of S7 this function is deprecated.
External name: addRaidBatch
Parameter count: seven
Return type: i4
Action: Adds a number of raids as one big batch. If the raids can be represented by just one displayed raid then that should be done. Each specified participant should receive the DKP that the corresponding raid rewards. The function may or may not be equal to multiple calls to Add raid with the corresponding calls to Add raid attendees.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
array<string> - An array of string where the i:th element is the name that the i:th raid should have. If only one name can be displayed then it should be the first.
array<string> - An array of string where the i:th element is the unix timestamp in seconds that the i:th raid should have. If only one timestamp can be displayed then it should be the first.
array<string> - An array of string where the i:th element is a description of the i:th raid. If only one description can be displayed then it should be the first.
array<double> - An array of double where the i:th element is the number of DKP that the i:th raid should award its participants.
array<array<string>> - An array of arrays where the i:th element contains all names of the people that participated in the i:th raid. The persons do not have to be registered on the server. If unregistered persons are not allowed then all unregistered persons should be ignored, but the rest should still be processed.

Return value

An unique identifier representing the raid that loot connected to the raid batch should be added to.

Add event

Deprecated: As of S7 this function is deprecated.
External name: addEvent
Parameter count: seven
Return type: void
Action: Adds an event to the server. The event should have the specified name, reward an participants. Optionally it should also have a specified time of addition and a specified note.

Parameters

string - The user name that should be used for authentication purposes.
string - The password that should be used for authentication purposes.
string - The name that the event should have.
string - The unix timestamp representing the point in time that the event should display having been added at. This parameter may optionally be ignored by the implementation.
array<string> - An array containing all names of the people that participated in the event. The persons do not have to be registered on the server. If unregistered persons are not allowed then all unregistered persons should be ignored, but the rest should still be processed.
string - The text that should be displayed to describe the event, e.g. as a small note. This parameter may optionally be ignored by the implementation.
double - The number of DKP that should be rewarded to participants of the event.

Get plugin version

Deprecated: As of S3 this function is deprecated.
External name: getPluginVersion
Parameter count: zero
Return type: string
Action: Desprecated, the function should only return a constant as detailed below.

Return value

The constant string "1.2.3".

Retrieved from "http://dkplp.org/wiki/Server_interface"

Category: Server interfaces

Views

Personal tools

Log in / create account

wiki

Search

Toolbox