ConvertArtificialLegacyId64ToEventId

Lua Code:

(method) LibHistoire:ConvertArtificialLegacyId64ToEventId(id64: string)
  -> id53: integer53|nil

Utility function to convert id64s that have been artificially created by a legacy listener to the new id53 equivalent.
Should be used one time only to convert all id64s that have been stored by the addon when switching to the new event processor api, since it's not the fastest operation.

@param id64 — The id64 to convert.
@return id53 — The converted id53 or nil if the id64 cannot be converted.

CreateGuildHistoryListener (deprecated)

This method will be removed in a future version. Use CreateGuildHistoryProcessor instead.

Lua Code:

(method) LibHistoire:CreateGuildHistoryListener(guildId: integer, category: integer)
  -> listener: GuildHistoryLegacyEventListener|nil

Creates a legacy listener object which emulates the old guild history api. See guildHistoryCache/GuildHistoryLegacyEventListener.lua for details.
It's highly recommended to transition to CreateGuildHistoryProcessor instead, to take better advantage of the new history api.

@param guildId — The id of the guild to listen to.
@param category — The legacy category to listen to. One of the GUILD_HISTORY_* constants. See guildHistoryCache/compatibility.lua for details.
@return listener — The created listener object or nil if no caches were found for the provided guildId and category.

See:

• GuildHistoryLegacyEventListener
• LibHistoire.CreateGuildHistoryProcessor

CreateGuildHistoryProcessor

Lua Code:

(method) LibHistoire:CreateGuildHistoryProcessor(guildId: integer, category: GuildHistoryEventCategory, addonName: string)
  -> processor: GuildHistoryEventProcessor|nil

Creates a processor object which can be configured before it starts sending history events to an addon. See guildHistoryCache/GuildHistoryEventProcessor.lua for details.

@param guildId — The id of the guild to process history events for.
@param category — The category to process history events for.
@param addonName — The name of the addon that is processing the events. This is used to allow users to identify addons that are registered to a category, as well as to provide better logging.
@return processor — The created processor object or nil if no caches were found for the provided guildId and category.

See:

• GuildHistoryEventProcessor

IsReady

Lua Code:

(method) LibHistoire:IsReady()
  -> isReady: boolean

This function can be used to check if the library is ready to be used. It will return true after the INITIALIZED callback has been fired.
When the library is not ready yet, make sure to register to the INITIALIZED callback to know when it is.

@return isReady — True if the library is ready to be used, false otherwise.

See:

• Callbacks.INITIALIZED

OnReady

Lua Code:

(method) LibHistoire:OnReady(callback: fun(lib: LibHistoire))

A convenience function to execute a callback when the library is ready. When the library is already initialized, the callback will be executed immediately.

@param callback — The function to call when the library is ready. It will receive the LibHistoire object as an argument.

See:

• Callbacks.INITIALIZED
• LibHistoire.IsReady

RegisterCallback

Lua Code:

(method) LibHistoire:RegisterCallback(callbackName: Callbacks, callback: function, ...any)

Register to a callback fired by the library. Usage is the same as with ZO_CallbackObject.RegisterCallback. You can find the list of exposed callbacks in api.lua

@param callbackName — One of the exposed callbacks.
@param callback — The function to call when the callback is fired.

See:

• Callbacks

UnregisterCallback

Lua Code:

(method) LibHistoire:UnregisterCallback(callbackName: Callbacks, callback: function, ...any)

Unregister from a callback fired by the library. Usage is the same as with ZO_CallbackObject.UnregisterCallback.

@param callbackName — One of the exposed callbacks.
@param callback — The function to unregister.

See:

• Callbacks

GetAddonName

Lua Code:

(method) GuildHistoryEventProcessor:GetAddonName()
  -> addonName: string

Returns the name of the addon that created the processor.

@return addonName — The name of the addon that created the processor.

GetCategory

Lua Code:

(method) GuildHistoryEventProcessor:GetCategory()
  -> category: GuildHistoryEventCategory

Returns the category.

@return category — The event category the processor is listening to.

GetGuildId

Lua Code:

(method) GuildHistoryEventProcessor:GetGuildId()
  -> guildId: integer

Returns the guild id.

@return guildId — The id of the guild the processor is listening to.

GetKey

Lua Code:

(method) GuildHistoryEventProcessor:GetKey()
  -> key: string

Returns a key consisting of server, guild id and history category, which can be used to store the last received eventId.

@return key — The key that identifies the processor.

GetPendingEventMetrics

Lua Code:

(method) GuildHistoryEventProcessor:GetPendingEventMetrics()
  -> numEventsRemaining: integer
  2. processingSpeed: integer
  3. timeLeft: integer

Returns information about history events that need to be sent to the processor.

@return numEventsRemaining — The amount of queued history events that are currently waiting to be processed by the processor.
@return processingSpeed — The processing speed in events per second (rolling average over 5 seconds).
@return timeLeft — The estimated time in seconds it takes to process the remaining events or -1 if it cannot be estimated.

IsRunning

Lua Code:

(method) GuildHistoryEventProcessor:IsRunning()
  -> running: boolean

Returns true while iterating over or listening for events.

@return running — true if the processor is currently running.

SetAfterEventId

Lua Code:

(method) GuildHistoryEventProcessor:SetAfterEventId(eventId: integer53)
  -> success: boolean

Allows to specify a start condition. The nextEventCallback will only return events which have a higher eventId.

@param eventId — An eventId to start after.
@return success — true if the condition was set successfully, false if the processor is already running.

SetAfterEventTime

Lua Code:

(method) GuildHistoryEventProcessor:SetAfterEventTime(eventTime: integer53)
  -> success: boolean

Allows to specify a start condition. The nextEventCallback will only receive events after the specified timestamp. Only is considered if no afterEventId has been specified.

@param eventTime — A timestamp to start after.
@return success — true if the condition was set successfully, false if the processor is already running.

SetBeforeEventId

Lua Code:

(method) GuildHistoryEventProcessor:SetBeforeEventId(eventId: integer53)
  -> success: boolean

Allows to specify an end condition. The nextEventCallback will only return events which have a lower eventId.

@param eventId — An eventId to end before.
@return success — true if the condition was set successfully, false if the processor is already running.

SetBeforeEventTime

Lua Code:

(method) GuildHistoryEventProcessor:SetBeforeEventTime(eventTime: integer53)
  -> success: boolean

Allows to specify an end condition. The nextEventCallback will only return events which have a lower timestamp. Only is considered if no beforeEventId has been specified.

@param eventTime — A timestamp to end before.
@return success — true if the condition was set successfully, false if the processor is already running.

SetEventCallback

Lua Code:

(method) GuildHistoryEventProcessor:SetEventCallback(callback: fun(event: ZO_GuildHistoryEventData_Base))
  -> success: boolean

Convenience method to set both callback types at once.

@param callback — The function that will be called for each missed event that was found.
@return success — true if the condition was set successfully, false if the processor is already running.

See:

• GuildHistoryEventProcessor.SetNextEventCallback
• GuildHistoryEventProcessor.SetMissedEventCallback

SetMissedEventCallback

Lua Code:

(method) GuildHistoryEventProcessor:SetMissedEventCallback(callback: fun(event: ZO_GuildHistoryEventData_Base))
  -> success: boolean

Sets a callback which will get passed events that had not previously been included in the managed range, but are inside the start and end criteria. The order of the events is not guaranteed.
If SetReceiveMissedEventsOutsideIterationRange is set to true, this callback will also receive events that are outside of the specified iteration range.
The callback will be handed an event object (see guildhistory_data.lua) which must not be stored or modified, as it can change after the function returns.

@param callback — The function that will be called for each missed event that was found.
@return success — true if the condition was set successfully, false if the processor is already running.

See:

• ZO_GuildHistoryEventData_Base
• GuildHistoryEventProcessor.SetReceiveMissedEventsOutsideIterationRange

SetNextEventCallback

Lua Code:

(method) GuildHistoryEventProcessor:SetNextEventCallback(callback: fun(event: ZO_GuildHistoryEventData_Base))
  -> success: boolean

Sets a callback which will get passed all events in the specified range in the correct historic order (sorted by eventId).
The callback will be handed an event object (see guildhistory_data.lua) which must not be stored or modified, as it can change after the function returns.

@param callback — The function that will be called for each event that is processed.
@return success — true if the condition was set successfully, false if the processor is already running.

See:

• ZO_GuildHistoryEventData_Base

SetOnStopCallback

Lua Code:

(method) GuildHistoryEventProcessor:SetOnStopCallback(callback: fun(reason: StopReason))
  -> success: boolean

Set a callback which is called after the listener has stopped.
Receives a reason (see lib.StopReason) why the processor has stopped.

@param callback — The function that will be called when the processor stops.
@return success — true if the condition was set successfully, false if the processor is already running.

See:

• LibHistoire.StopReason

SetReceiveMissedEventsOutsideIterationRange

Lua Code:

(method) GuildHistoryEventProcessor:SetReceiveMissedEventsOutsideIterationRange(shouldReceive: boolean)
  -> success: boolean

Controls if the processor should forward missed events outside of the specified iteration range to the missedEventCallback.

@param shouldReceive — true if missed events outside of the specified iteration range should be forwarded, false if they should be ignored.
@return success — true if the condition was set successfully, false if the processor is already running.

See:

• GuildHistoryEventProcessor.SetMissedEventCallback

SetRegisteredForFutureEventsCallback

Lua Code:

(method) GuildHistoryEventProcessor:SetRegisteredForFutureEventsCallback(callback: function)
  -> success: boolean

Sets a callback which is called when the processor starts waiting for future events.

@param callback — The function that will be called when the processor starts waiting for future events.
@return success — true if the condition was set successfully, false if the processor is already running.

SetStopOnLastCachedEvent

Lua Code:

(method) GuildHistoryEventProcessor:SetStopOnLastCachedEvent(shouldStop: boolean)
  -> success: boolean

Controls if the processor should stop instead of listening for future events when it runs out of events before encountering an end criteria.

@param shouldStop — true if the processor should stop when it runs out of events, false if it should wait for future events.
@return success — true if the condition was set successfully, false if the processor is already running.

Start

Lua Code:

(method) GuildHistoryEventProcessor:Start()
  -> started: boolean

Starts the processor and passes events to the specified callbacks asyncronously. The exact behavior depends on the set conditions and callbacks.

@return started — true if the processor was started successfully, false if it is already running.

StartIteratingTimeRange

Lua Code:

(method) GuildHistoryEventProcessor:StartIteratingTimeRange(startTime: integer53, endTime: integer53, eventCallback: fun(event: ZO_GuildHistoryEventData_Base), finishedCallback: fun(reason: StopReason))
  -> started: boolean

Convenience method to configure and start the processor to iterate over a specific time range and stop after it has passed all available events.

@param startTime — The start time of the range (inclusive).
@param endTime — The end time of the range (exclusive).
@param eventCallback — The function that will be called for each event that is processed.
@param finishedCallback — The function that will be called when the processor stops. Only when StopReason.ITERATION_COMPLETED is passed, all events in the range have been processed.
@return started — true if the processor was started successfully, false if it is already running.

See:

• GuildHistoryEventProcessor.SetAfterEventTime
• GuildHistoryEventProcessor.SetBeforeEventTime
• GuildHistoryEventProcessor.SetStopOnLastCachedEvent
• GuildHistoryEventProcessor.SetNextEventCallback
• GuildHistoryEventProcessor.SetOnStopCallback

StartStreaming

Lua Code:

(method) GuildHistoryEventProcessor:StartStreaming(lastProcessedId: integer53|nil, eventCallback: fun(event: ZO_GuildHistoryEventData_Base))
  -> started: boolean

Convenience method to start the processor with a callback and optionally only receive events after the specified eventId.

@param lastProcessedId — The last eventId that was processed by the addon or nil to start with the oldest managed event.
@param eventCallback — The function that will be called for each event that is processed. If not provided here, it has to be set with SetNextEventCallback beforehand, or the processor won't start.
@return started — true if the processor was started successfully, false if it is already running.

Stop

Lua Code:

(method) GuildHistoryEventProcessor:Stop()
  -> stopped: boolean

Stops iterating over stored events and unregisters the processor for future events.

@return stopped — true if the processor was stopped successfully, false if it is not running.

Callbacks.CATEGORY_LINKED

Fired when a category has linked the managed range to present events. The guildId and category are passed as arguments.

Callbacks.HISTORY_RESCAN_ENDED (deprecated)

Rescan no longer exists.

Callbacks.HISTORY_RESCAN_STARTED (deprecated)

Rescan no longer exists.

Callbacks.INITIALIZED

Fired when the library has finished setting everything up.
Any calls to the api (aside of registering for the event) should happen after this has fired.
It will receive the LibHistoire object as an argument.

Keep in mind that this may fire before EVENT_ADD_ON_LOADED, so make sure to check if the library is ready before listening to the callback.

See:

• LibHistoire.IsReady

Callbacks.LINKED_RANGE_FOUND (deprecated)

Use MANAGED_RANGE_FOUND instead.


See:

• Callbacks.MANAGED_RANGE_FOUND

Callbacks.LINKED_RANGE_LOST (deprecated)

Use MANAGED_RANGE_LOST instead.


See:

• Callbacks.MANAGED_RANGE_LOST

Callbacks.MANAGED_RANGE_FOUND

Fired when a new managed range has been found. The guildId and category are passed as arguments.
This happens when the managed range is established initially or after the managed range was lost.

Callbacks.MANAGED_RANGE_LOST

Fired when the managed range has been lost. The guildId and category are passed as arguments.
This could be due to the cache being deleted, the library detecting inconsistencies in its own save data or the user manually resetting the range.

StopReason.ITERATION_COMPLETED

An end condition has been set and the first event outside of the specified range was encountered

See:

• GuildHistoryEventProcessor.SetBeforeEventId
• GuildHistoryEventProcessor.SetBeforeEventTime

StopReason.LAST_CACHED_EVENT_REACHED

The stopOnLastCachedEvent flag has been set and the last cached event was reached

See:

• GuildHistoryEventProcessor.SetStopOnLastCachedEvent

StopReason.MANAGED_RANGE_LOST

The managed range was lost (fires right after MANAGED_RANGE_LOST callback)

See:

• Callbacks.MANAGED_RANGE_LOST

StopReason.MANUAL_STOP

Stop has been called by the addon

See:

• GuildHistoryEventProcessor.Stop