Since DataStore is divided into several modules, you will be able to call two kinds of methods through the DataStore global objects : DataStore's own methods, which are pretty common like :GetCharacter(), and module-specific methods, which obviously belong to their respective modules and will not be described here.

Calling a method

Regardless of this difference, method calls are identical.

A call to a native DataStore method looks like this (implemented in DataStore\DataStore.lua) :

local character = DataStore:GetCharacter()

A call to a module-specific method looks like this (sample : GetCharacterLevel() implemented in DataStore_Characters\DataStore_Characters.lua)

local level = DataStore:GetCharacterLevel(character)

Character-based methods

DataStore also recognizes another specific type of methods, which is the character-based method type. The point of these methods is to provide partial integrity check inside DataStore.

local character = DataStore:GetCharacter()
local level = DataStore:GetCharacterLevel(character)

In this example, you see that the variable "character" is passed as first argument of :GetCharacterLevel(). If you look at the implementation of these two methods, you will see that DataStore:GetCharacter() returns a string, whereas :GetCharacterLevel() expects a table as first argument. DataStore takes care of translating a string argument into a table that can directly be used inside the method, relieving modules from having to perform type-checking on this argument.

The thing to keep in mind when calling these methods is that the character key is a simple string containing the account, realm and name of the character, and that this key is always the first argument of a character-based method.

DataStore provides several methods to manage characters (see examples below), but you are free to manually create your character key if you want to :

local name = UnitName("player")
local realm = GetRealmName()
local account = "Default"
local character = format("%s.%s.%s", account, realm, name)

DataStore:GetCharacter(name, realm, account)

This is the method you will use to get the character key of a specific character.
All 3 parameters are optional and default to the current character (as returned by UnitName("player")), the current realm (as returned by GetRealmName()), and to the current account (by convention, I called it "Default").

Samples:

-- Getting the current character, on the current realm and current account
local character = DataStore:GetCharacter()

-- Getting the character "Bankaltone", on the current realm and current account
local character = DataStore:GetCharacter("Bankaltone")

-- Getting the character "Bankalttwo", on the realm "Sinstralis" and current account
local character = DataStore:GetCharacter("Bankalttwo", "Sinstralis")

-- Getting the character "Bankalttwo", on the realm "Sinstralis"
-- and on the account called "MyWife"
local character = DataStore:GetCharacter("Bankalttwo", "Sinstralis", "MyWife")

DataStore:GetCharacters(realm, account)

Used to loop through all characters on a given realm/account. Both arguments default to current realm/account.

Sample:

for characterName, character in pairs(DataStore:GetCharacters(realm, account)) do
   -- do stuff with characterName only
   -- or do stuff with the "character" key
   local level = DataStore:GetCharacterLevel(character)
end

DataStore:GetRealms(account)

Used to loop through all realms on a given account. Argument defaults to current account.

Sample:

for realm in pairs(DataStore:GetRealms(account)) do
end

DataStore:GetAccounts()

Used to loop through all accounts. The combination of this and two previous methods allows you to loop through all characters known by DataStore :

for account in pairs(DataStore:GetAccounts()) do
   for realm in pairs(DataStore:GetRealms(account)) do
      for characterName, character in pairs(DataStore:GetCharacters(realm, account)) do
         -- do stuff with characterName only
         -- or do stuff with the "character" key
         local level = DataStore:GetCharacterLevel(character)
      end
   end
end