Thread: New Guild History API
View Single Post
11/01/23, 03:15 PM   #1
sirinsidiator
 
sirinsidiator's Avatar
AddOn Author - Click to view addons
Join Date: Apr 2014
Posts: 1,579
New Guild History API
Thanks to the tireless efforts of Dan, we are finally getting a new and improved Guild History API with Update 41.
Here's a first look at the new API and how it will work.

Code:
* ClearGuildHistoryCache(*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]:nilable* _category_)
** _Returns:_ *bool* _success_

* GetNumGuildHistoryEvents(*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]* _category_)
** _Returns:_ *integer* _numEvents_

* GetGuildHistoryEventIndicesForTimeRange(*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]* _category_, *integer53* _newestTimeS_, *integer53* _oldestTimeS_)
** _Returns:_ *luaindex:nilable* _newestEventIndex_, *luaindex:nilable* _oldestEventIndex_

* GetOldestGuildHistoryEventIndexForUpToDateEventsWithoutGaps(*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]* _category_)
** _Returns:_ *luaindex:nilable* _oldestEventIndex_

* GetGuildHistoryEventId(*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]* _category_, *luaindex* _eventIndex_)
** _Returns:_ *integer53* _eventId_

* GetGuildHistoryRosterEventInfo(*integer* _guildId_, *luaindex* _eventIndex_)
** _Returns:_ *integer53* _eventId_, *integer53* _timestampS_, *[GuildHistoryRosterEvent|#GuildHistoryRosterEvent]* _eventType_, *string* _actingDisplayName_, *string* _targetDisplayName_, *integer:nilable* _rankId_

* GetGuildHistoryBankedItemEventInfo(*integer* _guildId_, *luaindex* _eventIndex_)
** _Returns:_ *integer53* _eventId_, *integer53* _timestampS_, *[GuildHistoryBankedItemEvent|#GuildHistoryBankedItemEvent]* _eventType_, *string* _displayName_, *string* _itemLink_, *integer* _quantity_

* GetGuildHistoryBankedCurrencyEventInfo(*integer* _guildId_, *luaindex* _eventIndex_)
** _Returns:_ *integer53* _eventId_, *integer53* _timestampS_, *[GuildHistoryBankedCurrencyEvent|#GuildHistoryBankedCurrencyEvent]* _eventType_, *string* _displayName_, *[CurrencyType|#CurrencyType]* _currencyType_, *integer* _amount_, *string* _kioskName_

* GetGuildHistoryTraderEventInfo(*integer* _guildId_, *luaindex* _eventIndex_)
** _Returns:_ *integer53* _eventId_, *integer53* _timestampS_, *[GuildHistoryTraderEvent|#GuildHistoryTraderEvent]* _eventType_, *string* _sellerDisplayName_, *string* _buyerDisplayName_, *string* _itemLink_, *integer* _quantity_, *integer* _price_, *integer* _tax_

* GetGuildHistoryMilestoneEventInfo(*integer* _guildId_, *luaindex* _eventIndex_)
** _Returns:_ *integer53* _eventId_, *integer53* _timestampS_, *[GuildHistoryMilestoneEvent|#GuildHistoryMilestoneEvent]* _eventType_

* GetGuildHistoryActivityEventInfo(*integer* _guildId_, *luaindex* _eventIndex_)
** _Returns:_ *integer53* _eventId_, *integer53* _timestampS_, *[GuildHistoryActivityEvent|#GuildHistoryActivityEvent]* _eventType_, *string* _displayName_

* GetGuildHistoryAvAActivityEventInfo(*integer* _guildId_, *luaindex* _eventIndex_)
** _Returns:_ *integer53* _eventId_, *integer53* _timestampS_, *[GuildHistoryAvAActivityEvent|#GuildHistoryAvAActivityEvent]* _eventType_, *string* _displayName_, *integer* _keepId_, *integer* _campaignId_

* CreateGuildHistoryRequest(*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]* _category_, *integer53* _newestTimeS_, *integer53* _oldestTimeS_)
** _Returns:_ *integer* _requestId_

* GetGuildHistoryRequestFlags(*integer* _requestId_)
** _Returns:_ *[GuildHistoryRequestFlags|#GuildHistoryRequestFlags]* _flags_

* IsGuildHistoryRequestComplete(*integer* _requestId_)
** _Returns:_ *bool* _isComplete_

* DoesGuildHistoryHaveOutstandingRequest()
** _Returns:_ *bool* _hasOutstandingRequest_

* RequestMoreGuildHistoryEvents(*integer* _requestId_, *bool* _queueRequestIfOnCooldown_)
** _Returns:_ *[GuildHistoryDataReadyState|#GuildHistoryDataReadyState]* _readyState_

* GetNumGuildHistoryEventRanges(*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]* _category_)
** _Returns:_ *integer* _numGuildHistoryEventRanges_

* GetGuildHistoryEventRangeInfo(*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]* _category_, *luaindex* _rangeIndex_)
** _Returns:_ *integer53* _newestTimeS_, *integer53* _oldestTimeS_, *integer53* _newestEventId_, *integer53* _oldestEventId_

* DestroyGuildHistoryRequest(*integer* _requestId_)
** _Returns:_ *bool* _successfullyDestroyed_

* EVENT_GUILD_HISTORY_CATEGORY_UPDATED (*integer* _guildId_, *[GuildHistoryEventCategory|#GuildHistoryEventCategory]* _eventCategory_, *[GuildHistoryCategoryUpdateFlags|#GuildHistoryCategoryUpdateFlags]* _flags_)

h5. GuildHistoryActivityEvent
* GUILD_HISTORY_ACTIVITY_EVENT_ABOUT_US_EDITED
* GUILD_HISTORY_ACTIVITY_EVENT_MOTD_EDITED
* GUILD_HISTORY_ACTIVITY_EVENT_RECRUITMENT_LISTED
* GUILD_HISTORY_ACTIVITY_EVENT_RECRUITMENT_UNLISTED


h5. GuildHistoryAvAActivityEvent
* GUILD_HISTORY_AVA_ACTIVITY_EVENT_KEEP_CLAIMED
* GUILD_HISTORY_AVA_ACTIVITY_EVENT_KEEP_LOST
* GUILD_HISTORY_AVA_ACTIVITY_EVENT_KEEP_RELEASED


h5. GuildHistoryBankedCurrencyEvent
* GUILD_HISTORY_BANKED_CURRENCY_EVENT_DEPOSITED
* GUILD_HISTORY_BANKED_CURRENCY_EVENT_HERALDRY_EDITED
* GUILD_HISTORY_BANKED_CURRENCY_EVENT_KIOSK_BID
* GUILD_HISTORY_BANKED_CURRENCY_EVENT_KIOSK_BID_REFUND
* GUILD_HISTORY_BANKED_CURRENCY_EVENT_KIOSK_PURCHASED
* GUILD_HISTORY_BANKED_CURRENCY_EVENT_WITHDRAWN


h5. GuildHistoryBankedItemEvent
* GUILD_HISTORY_BANKED_ITEM_EVENT_ADDED
* GUILD_HISTORY_BANKED_ITEM_EVENT_REMOVED


h5. GuildHistoryCategoryUpdateFlags
* GUILD_HISTORY_CATEGORY_UPDATE_FLAG_NEW_INFO
* GUILD_HISTORY_CATEGORY_UPDATE_FLAG_REFRESHED
* GUILD_HISTORY_CATEGORY_UPDATE_FLAG_RESPONSE_RECEIVED


h5. GuildHistoryDataReadyState
* GUILD_HISTORY_DATA_READY_STATE_INVALID_REQUEST
* GUILD_HISTORY_DATA_READY_STATE_ON_COOLDOWN
* GUILD_HISTORY_DATA_READY_STATE_READY
* GUILD_HISTORY_DATA_READY_STATE_RESPONSE_PENDING


h5. GuildHistoryEventCategory
* GUILD_HISTORY_EVENT_CATEGORY_ACTIVITY
* GUILD_HISTORY_EVENT_CATEGORY_AVA_ACTIVITY
* GUILD_HISTORY_EVENT_CATEGORY_BANKED_CURRENCY
* GUILD_HISTORY_EVENT_CATEGORY_BANKED_ITEM
* GUILD_HISTORY_EVENT_CATEGORY_MILESTONE
* GUILD_HISTORY_EVENT_CATEGORY_ROSTER
* GUILD_HISTORY_EVENT_CATEGORY_TRADER


h5. GuildHistoryEventSubcategory
* GUILD_HISTORY_EVENT_SUBCATEGORY_ALL
* GUILD_HISTORY_EVENT_SUBCATEGORY_DEPOSITS
* GUILD_HISTORY_EVENT_SUBCATEGORY_HIRED_TRADER
* GUILD_HISTORY_EVENT_SUBCATEGORY_OWNERSHIP
* GUILD_HISTORY_EVENT_SUBCATEGORY_PURCHASES
* GUILD_HISTORY_EVENT_SUBCATEGORY_WITHDRAWALS


h5. GuildHistoryMilestoneEvent
* GUILD_HISTORY_MILESTONE_EVENT_BANK_LOCKED
* GUILD_HISTORY_MILESTONE_EVENT_BANK_UNLOCKED
* GUILD_HISTORY_MILESTONE_EVENT_KIOSK_LOCKED
* GUILD_HISTORY_MILESTONE_EVENT_KIOSK_UNLOCKED
* GUILD_HISTORY_MILESTONE_EVENT_STORE_LOCKED
* GUILD_HISTORY_MILESTONE_EVENT_STORE_UNLOCKED
* GUILD_HISTORY_MILESTONE_EVENT_TABARD_LOCKED
* GUILD_HISTORY_MILESTONE_EVENT_TABARD_UNLOCKED


h5. GuildHistoryRequestFlags
* GUILD_HISTORY_REQUEST_FLAG_CHUNKS_DIRTY
* GUILD_HISTORY_REQUEST_FLAG_COMPLETE
* GUILD_HISTORY_REQUEST_FLAG_CREATED_FROM_ADDON
* GUILD_HISTORY_REQUEST_FLAG_QUEUED
* GUILD_HISTORY_REQUEST_FLAG_QUEUED_FROM_ADDON
* GUILD_HISTORY_REQUEST_FLAG_RESPONSE_PENDING


h5. GuildHistoryRosterEvent
* GUILD_HISTORY_ROSTER_EVENT_ADDED_TO_BLACKLIST
* GUILD_HISTORY_ROSTER_EVENT_APPLICATION_ACCEPTED
* GUILD_HISTORY_ROSTER_EVENT_APPLICATION_DECLINED
* GUILD_HISTORY_ROSTER_EVENT_DEMOTE
* GUILD_HISTORY_ROSTER_EVENT_EDIT_BLACKLIST_NOTE
* GUILD_HISTORY_ROSTER_EVENT_INVITE
* GUILD_HISTORY_ROSTER_EVENT_JOIN
* GUILD_HISTORY_ROSTER_EVENT_KICKED
* GUILD_HISTORY_ROSTER_EVENT_LEAVE
* GUILD_HISTORY_ROSTER_EVENT_PROMOTE
* GUILD_HISTORY_ROSTER_EVENT_REMOVED_FROM_BLACKLIST


h5. GuildHistoryTraderEvent
* GUILD_HISTORY_TRADER_EVENT_ITEM_SOLD
As you can see in the provided documentation, addons now can request data for specific time ranges without having to load all the history up to that point.
The server will then return the requested data in chunks of 500 entries at a time (up from 100 in the old system), which can be accessed using the new GetNumGuildHistoryEventRanges and GetGuildHistoryEventRangeInfo functions.

Data will be available on the server for 30 days for all categories except the roster and milestone category, which will allow to access data for up to 180 days.
The best part about it is that all the requested data is now cached locally, so that it can be accessed without having to query the server again.
By default the cache will keep data for 30 days, but a setting will be available to choose an arbitrary time frame.

In addition there will also be a helper class that can be used to simplify the process of requesting data from the server.

Lua Code:
  1. ZO_GuildHistoryRequest = ZO_InitializingObject:Subclass()
  2.  
  3. function ZO_GuildHistoryRequest:Initialize(guildId, eventCategory, newestTimeS, oldestTimeS)
  4.     self.guildId = guildId
  5.     self.eventCategory = eventCategory
  6.     self.newestTimeS = newestTimeS
  7.     self.oldestTimeS = oldestTimeS
  8.     self.requestId = CreateGuildHistoryRequest(guildId, eventCategory, newestTimeS, oldestTimeS)
  9. end
  10.  
  11. function ZO_GuildHistoryRequest:GetRequestId()
  12.     return self.requestId
  13. end
  14.  
  15. function ZO_GuildHistoryRequest:IsValid()
  16.     return self.requestId ~= 0
  17. end
  18.  
  19. function ZO_GuildHistoryRequest:GetFlags()
  20.     return GetGuildHistoryRequestFlags(self.requestId)
  21. end
  22.  
  23. function ZO_GuildHistoryRequest:IsComplete()
  24.     return IsGuildHistoryRequestComplete(self.requestId)
  25. end
  26.  
  27. function ZO_GuildHistoryRequest:IsRequestQueued()
  28.     return ZO_FlagHelpers.MaskHasFlag(self:GetFlags(), GUILD_HISTORY_REQUEST_FLAG_QUEUED)
  29. end
  30.  
  31. function ZO_GuildHistoryRequest:RequestMoreEvents(queueRequestIfOnCooldown)
  32.     local guildHistoryDataReadyState = RequestMoreGuildHistoryEvents(self.requestId, queueRequestIfOnCooldown)
  33.     return guildHistoryDataReadyState
  34. end

The new system is a complete rewrite, so any addons that directly rely on the old API will need to be updated to work with the new one.

I will also try my best to adapt LibHistoire to the new system so that addons depending on it will continue to work without any or only with minimal changes on their part.
However I decided to remove all the caching functionality from the library, so if you feel like you want to keep any of the old data around, you will need to export it before Update 41 arrives early next year.

Also keep in mind that this is a very early preview and there is still some time for details to change.
If you have questions, suggestions or any other feedback, please feel free to reply to this thread.
  Reply With Quote