WowAce

Pulling the library to your your addon

local mod = {}
LibStub("LibRealmDetect-1.0"):Embed(mod)
-- or ...
-- local rdlib = LibStub("LibRealmDetect-1.0"):Library()

API functions

lib:GetCurrentRealm()

Returns

realmName, isUncertain

realmName

(string) - The assumed name of the realm currently connected to, or the last known realm if isUncertain is 1.

isUncertain

(1 / nil) - whether the current realm is not known for sure (i.e., during the period of /who queries being made when a realm phase is detected, and awaiting their results).

Usage

local realmName, isUncertain = lib:GetCurrentRealm()

if isUncertain then
   print(("Current realm unknown, last known realm: %s"):format(realmName or "none")
else
   print(("Current realm: %s"):format(realmName))
end

lib:GetHomeRealm()

Returns

realmName

realmName

(string) - The name of a characters home realm (somewhat equivalent to calling _G.GetRealmName())

lib.RD_RegisterCallback(myTable or “myAddonId”, “eventName”[, method[, arg]])

Parameters

myTable

(table) - Your addon object.

"myAddonId"

(string) - A unique string identifier for your callback.

"eventName"

(string) - the name of the event you want to listen to

method

(string or function) - which method to call. If string, myTable["method"] will be called. If left out (nil), myTable["eventName"] will be called.

lib.RD_UnregisterCallback(myTable or "myAddonId", "eventName")

Parameters

myTable

(table) - Your addon object.

"myAddonId"

(string) - A unique string identifier (the same it was registered with) for your callback.

"eventName"

(string) - the name of the event that you no longer wish to receive.

Callback events

REALMDETECT_REALM_UNKNOWN(lastKnownRealm)

Fires when a possible realm change is detected. If it is possible to assume that the character is in its home realm (e.g is not in a cross-realm group), this event will NOT fire. REALMDETECT_REALM_KNOWN will instead fire immediately.

Arguments

lastKnownRealm

(string) Name of the last known realm the character was in.

REALMDETECT_REALM_KNOWN(realmName, changed)

Fires when the current realm is known (possibly after being in an unknown state). This event might fire even when no realm change takes place (e.g. crossing CRZ borders or moving into a non-phasing zone such as Orgrimmar or Stormwind). Whether the realm did change is given as the second argument.

Arguments

realmName

(string) Name of the current (assumed) realm.

changed

(boolean) true if the realm has changed, false otherwise (no realm change took place).

REALMDETECT_ERROR_NOT_ENOUGH_PLAYERS_FOUND()

Fires if the character cannot be assumed to be in its home realm AND if not enough players can be found in the current realm to be sure of its name.

REALMDETECT_ERROR_NO_FACTION()

Fires if the character has no faction AND cannot be assumed to be in its home realm. This event will fire only once per session, after which whenever the character is in a group, the current realm will remain uncertain.

Example

local mod = {}
LibStub("LibRealmDetect-1.0"):Embed(mod)

mod.RDevents = {}

function mod.RDevents:REALMDETECT_REALM_KNOWN(realm, hasChanged)
  print(("Realm is KNOWN, it is... %s! %s"):format(realm, hasChanged and "It's a new realm!" or "No changes here..."))
end

function mod.RDevents:REALMDETECT_REALM_UNKNOWN(lastKnownRealm)
  print(("Realm is UNKNOWN! Last known realm was %s"):format(lastKnownRealm))
end

function mod.RDevents:REALMDETECT_ERROR_NOT_ENOUGH_PLAYERS_FOUND()
  print("such dead realm, wow!")
end

function mod.RDevents:REALMDETECT_ERROR_NO_FACTION()
  print("there is no faction")
end

for event, func in pairs(mod.RDevents) do
  mod.RD_RegisterCallback(mod, event, func)
end