Platform.announcement_recipient.GetAnnouncementRecipientGroupMembership

呼叫方式

addon.Platform:GetAnnouncementRecipientGroupMembership(recipient, raidOnly)

可直接透過 addon 使用，不需要相依項目。

作用

將確切的施法對象名稱與目前有限的隊伍或團隊名單進行比對，然後透過單位代碼觀測其成員身分。名單資料缺少、含義不明確或正在變化時維持為無法使用；絕不讀取所選目標，也不在施法之間保留狀態。

參數

名稱	類型	作用
`self`	`RMPlatform`	Rotation Master 平台轉接器（使用冒號呼叫時隱含傳入）。
`recipient`	`string`	為這次施法記錄的確切可讀對象名稱。
`raidOnly`	`boolean \| nil`	為 true 時只檢查團隊成員身分；為 false 或 nil 時檢查隊伍或團隊。

傳回值

1	`boolean \| nil`	觀測到的成員身分；無法使用時為 nil。
2	`string \| nil`	結果為 nil 時的驗證或可用性原因。

版本

內建輔助函式在每個版本上都會註冊。不同的是它們讀取的遊戲 API；某個 API 不存在時，輔助函式會改用備用方式，或傳回 nil 並附上原因。

該版本無法使用（原因請見提示）
僅在暴雪的棄用相容層開啟時

遊戲 API
`GetNormalizedRealmName`
`UnitExists`
`UnitGUID`
`UnitName`
`canaccessvalue`

機密值（正式版與永久）

在正式版與永久上，遊戲交給插件的是機密值。此輔助函式會檢查它讀取的內容（addon.Platform:CanReadValue），遇到無法比較的機密值時，會傳回 nil 並附上原因（例如 restricted-value），而不是傳回該機密值。請將 nil 視為無法使用，而非假。

範例

local name = UnitName("target")
if type(name) ~= "string" then return nil end
local member = addon.Platform:GetAnnouncementRecipientGroupMembership(name, false)
if member == nil then return nil end
return member

原始碼

Platform/announcement_recipient.lua，第 24 行。在遊戲中為唯讀；「複製」會產生一份可編輯的複本。

Platform.announcement_recipient.GetAnnouncementRecipientGroupMembership(self, recipient, raidOnly)

    if not self:CanReadValue(recipient) or not self:CanReadValue(raidOnly) then return nil,'restricted-value' end
    if type(recipient)~='string' or recipient=='' or #recipient>256 then return nil,'cast-recipient-unavailable' end
    if raidOnly~=nil and type(raidOnly)~='boolean' then return nil,'invalid-group-query' end
    local grouped,reason=self:GetGroupMembership(raidOnly)
    if grouped~=true then return grouped,reason end
    local raid,why=self:GetGroupMembership(true)
    if raid==nil then return nil,why end
    local exists,name,guid,normalized=UnitExists,UnitName,UnitGUID,GetNormalizedRealmName
    local groupQuery=self.GetGroupMembership
    local membership=self.GetUnitGroupMembership
    if type(exists)~='function' or type(name)~='function' or type(guid)~='function' or type(membership)~='function' then return nil,'missing-api' end
    local function read(unit)
        local ok,present=pcall(exists,unit)
        if not ok or not self:CanReadValue(present) or type(present)~='boolean' then return nil end
        if not present then return false end
        local named,first,realm=pcall(name,unit)
        local identified,identity=pcall(guid,unit)
        if not named or not identified or not self:CanReadValue(first) or not self:CanReadValue(realm) or not self:CanReadValue(identity) then return nil end
        if canaccessvalue and not canaccessvalue(first) then return nil end
        if canaccessvalue and not canaccessvalue(realm) then return nil end
        if canaccessvalue and not canaccessvalue(identity) then return nil end
        if type(first)~='string' or first=='' or #first>256 or type(identity)~='string' or identity=='' or #identity>256 then return nil end
        if realm~=nil and type(realm)~='string' then return nil end
        if realm==nil or realm=='' then
            if type(normalized)=='function' then
                local got,value=pcall(normalized)
                if not got or not self:CanReadValue(value) then return nil end
                if canaccessvalue and not canaccessvalue(value) then return nil end
                if type(value)=='string' and value~='' and #value<=256 then realm=value end
            end
        end
        return {first=first,full=type(realm)=='string' and realm~='' and first..'-'..realm or nil,guid=identity}
    end
    local function scan()
        local rows,selected,count={},nil,0
        for index=raid and 1 or 0,raid and 40 or 4 do
            local unit=raid and 'raid'..index or index==0 and 'player' or 'party'..index
            local record=read(unit)
            if record==nil then return nil,'group-data-unavailable' end
            rows[unit]=record
            if record then
                count=count+1
                if recipient==record.first or recipient==record.full then
                    if selected then return nil,'cast-recipient-ambiguous' end
                    selected=unit
                elseif not record.full and recipient:sub(1,#record.first+1)==record.first..'-' then
                    return nil,'cast-recipient-unavailable'
                end
            end
        end
        if count==0 then return nil,'group-data-unavailable' end
        return rows,selected
    end
    local before,selected=scan()
    if not before then return nil,selected end
    local member,failure=false,nil
    if selected then member,failure=membership(self,selected,raidOnly) end
    -- Native calls and extension callbacks may reenter. Re-read the complete
    -- bounded roster after membership/context reads, including negative results:
    -- a stale false must not turn a NOT condition into permission to announce.
    local currentGroup=self:GetGroupMembership(raidOnly)
    local currentRaid=self:GetGroupMembership(true)
    local after,matched=scan()
    if exists~=UnitExists or name~=UnitName or guid~=UnitGUID or normalized~=GetNormalizedRealmName
        or membership~=self.GetUnitGroupMembership or groupQuery~=self.GetGroupMembership
        or currentGroup~=grouped or currentRaid~=raid or not after or matched~=selected then return nil,'group-data-unavailable' end
    for unit,record in pairs(before) do
        local fresh=after[unit]
        if type(record)~=type(fresh) then return nil,'group-data-unavailable' end
        if record and (fresh.guid~=record.guid or fresh.first~=record.first or fresh.full~=record.full) then return nil,'group-data-unavailable' end
    end
    return member,failure

返回函式參考