WhoLib

From WowAce Wiki
Jump to: navigation, search

Welcome to WhoLib-1.0!

  • An Interface for a informations about an user
  • Better event for returned who's
  • Queing of /who and SendWho()
  • A much better who interface, with gurantee to be executed & callback

(It will be ALLWAYS "WhoLib-1.0" cause it is not possible to run two of these!!)

API Documentation

:UserInfo(name [, opts])

Args

name 
string - the exact name of an player
opts 
table - options
opts.queue 
number - queue of this query (see below) - .WHOLIB_QUEUE_QUIET (default) or .WHOLIB_QUEUE_SCANNING
opts.timeout 
number - if the the result is cached, and not older than timeout minutes then the cache will be retuned, negative value: allways use cache (if available), otherwise: send a who query, default: 5 (minutes)
opts.callback 
function or string - will be called after this query is executed
function - "callback(...)"
string - method call, requies handler - "handler:callback(...)"
opts.handler 
table - see above, default: calling object
opts.flags 
number - one of more flags or'ed together, see Flags (bit.bor(flag1, flag2 [, flag3 [, ...]]))

Returns

nil 
if there was no appropriate cache
false 
see Flags: WHOLIB_FLAG_ALLWAYS_CALLBACK
user, time 
for cached results
user 
table with the user's informations
user.Name 
string - name of the player
user.Online 
true if online, false if offline, nil if unknown (more results than could be displayed)
if Online is not true than all following entries will be from the last successful call, or nil
user.Guild 
string - guild or ''
user.Class 
string - class
user.Race 
string - race
user.Level 
string - level
user.Zone 
string - zone
time 
the minutes how old the data was

Remarks

If you're only interested in this feature, then you don't have to read about :Who() and WHOLIB_QUERY_RESULT.

Do not use .WHOLIB_FLAG_ALLWAYS_CALLBACK when scanning a list over and over again, do a 5 sec pause after a cached return, cause you may have a short list and a cache time so high that all entries may be cached and in that case this function DO generate an almost infinite loop!

Callback

When a callback function is given and the function did'nt returned immediately then the callback will be raised when they're a result. The callback function will receive the same arguments as :UserInfo() would return.

Flags

.WHOLIB_FLAG_ALLWAYS_CALLBACK 
if :UserInfo() would return the cached data, raise the callback with that data instead and return false

Example

-- long version
local user, time = self:UserData(friendsname, { callback = 'UserDataReturned' } )
if(user)then
  -- the data was immediately available
  self:UserDataReturned(user, time)
else
  -- nothing
  -- we will be called when the data is available
end

-- short version
self:UserData(friendsname, { callback = 'UserDataReturned', flags = self.WHOLIB_FLAG_ALLWAYS_CALLBACK } )

-- callback function
function mod:UserDataReturned(user, time)
  local state
  if(user.Online == true)then
    state = 'Online'
  elseif(user.Online == false)then
    state = 'Offline'
  else
    -- user.Online will ne nil
    state = 'Unknown'
  end
  DEFAULT_CHAT_FRAME:AddMessage(user.Name .. ' is ' .. state)
end

:CachedUserInfo(name)

Args

name 
string - the exact name of an player

Returnes

nil 
if there was no appropriate cache
user, time 
for cached results
identical to :UserInfo()

Event: WHOLIB_QUERY_RESULT - query, results, complete, name

Args

query 
string - search string
results 
table - numeric iteratable table of results
results[i].Name 
string - name of the player
results[i].Online 
true if online, false if offline, nil if unknown (more results than could be displayed)
results[i].Guild 
string - guild or ''
results[i].Class 
string - class
results[i].Race 
string - race
results[i].Level 
string - level
results[i].Zone 
string - zone
complete 
boolean - shows whether all results could be returned (true) or not (false), if not, do a more specific query
name 
string - if the query was initiated by a :UserInfo() call, then this is the player name of the :UserInfo() call, otherwise nil

Remarks

The results table and the sub tables should not be stored or modified!
(It is exactly the same for all addons which have this event registered.)

All these fields are returned when any one call "/who" "SendWho()" or :Who(), even when the results are displayed in the chat.

Example

function mod:OnEnable()
   ...
   self:RegisterEvent('WHOLIB_QUERY_RESULT', 'DisplayPlayers')
   ...
end

function mod:DisplayPlayers(query, results, complete)
   if(not complete)then
      DEFAULT_CHAT_FRAME:AddMessage('There were more Players than here shown!')
   end
   for _,result in pairs(results) do
      DEFAULT_CHAT_FRAME:AddMessage('Player ' .. result.Name .. ' is currently in ' .. result.Zone)
   end
end

:Who(query [ , opts])

Args

query 
string - the search string
opts 
table - options
opts.queue 
number - queue of this query (see below) - .WHOLIB_QUEUE_QUIET (default) or .WHOLIB_QUEUE_USER or .WHOLIB_QUEUE_SCANNING
opts.callback 
function or string - will be called after this query is executed
function - "callback(...)"
string - method call, requies handler - "handler:callback(...)"
opts.handler 
table - see above, default: calling object

Returns

nil

Remarks

Everything except query will be ignored when the queue is .WHOLIB_QUEUE_USER.

If you've already registered WHOLIB_QUERY_RESULT then you may be don't need a callback.

Callback

When a callback function is given then the callback will be raised after the query is executed. The callback function will receive the same arguments as the event :WHOLIB_QUERY_RESULT has.

Example

self:Who({query = 'n-' .. friendsname, queue = self.WHOLIB_QUERY_QUIET, callback = 'DisplayPlayers'})
-- self.DisplayPlayers is in the example above

Constants

.WHOLIB_QUEUE_USER

.WHOLIB_QUEUE_QUIET

.WHOLIB_QUEUE_SCANNING

.WHOLIB_FLAG_ALLWAYS_CALLBACK

Queues

WHOLIB_QUEUE_USER

used on user queries (e.g. "/who", SocialFrame's Who)

will display the results in chat if only some, or in who-frame if more.

WHOLIB_QUEUE_QUIET

should be standard queue for addon queries, which aren't for scanning, and do not result in a user action: use .WHOLIB_QUEUE_USER

will neither show chat messages nor who-frame.

will be slowly queried while the WhoFrame is open.

WHOLIB_QUEUE_SCANNING

use for scanning

will neither show chat messages nor who-frame.

will not be queried while the WhoFrame is open.

Remarks

At first the .WHOLIB_QUEUE_USER queries will be executed, then the .WHOLIB_QUEUE_QUIET and at last the .WHOLIB_QUEUE_SCANNING.

Debug

When debugging is enabled then the chat will be filled with added/returned entries, one for each query.

21:01:40 WhoLib: [3] added "n-Lager", queues=0, 0, 1
21:01:40 WhoLib: [3] returned "n-Lager", total=0, queues=0, 0, 0

The [4] means Queue 4 = WHOLIB_QUEUE_SCANNING, each query will at first be "added" and later "returned", on returned queries the total number of entries wil also be printed. The "queues=0, 0, 0, 1" means that 0 queries are in the .WHOLIB_QUEUE_USER queue, 0 in .WHOLIB_QUEUE_QUIET, and 1 (the added one) in .WHOLIB_QUEUE_SCANNING.

For :UserInfo() even more entries will be printed.

:SetWhoLibDebug(bool)

Enables or disables the debugging.

/wholibdebug

Enables or disables the debugging.

Non Ace scripts

Example

local MyAddon_WhoLib = AceLibrary and AceLibrary('WhoLib-1.0')
MyAddon_WhoLib:SetWhoLibDebug(true)
MyAddon_WhoLib:Who({query = 'n-myfriend', queue = MyAddon_WhoLib.WHOLIB_QUEUE_QUIET, callback = wholibcallback})

function wholibcallback(query, results, complete)
  -- itentical parameters to DisplayPlayers in example above
end

TODO

  • localization
  • maybe better english texts
  • cleaning code? fixing the activate/deactivate/external?

Remarks

if someone wants to help me, just drop a note - or do it!

(I can't do it in the next time, cause I will first finish my other project, which is the reason why I've created this!)


ALeX Kazik - alx@kazik.de