WoW:API GetAuctionItemInfo: Difference between revisions

From AddOn Studio
Jump to navigation Jump to search
No edit summary
m (Move page script moved page API GetAuctionItemInfo to API GetAuctionItemInfo without leaving a redirect)
 
(7 intermediate revisions by 6 users not shown)
Line 1: Line 1:
<center>'''GetAuctionItemInfo''' ''-Documentation by Sarf-''</center>
{{wowapi}}
 
Retrieves info about one item in the current retrieved list of items from the Auction House.
Retrieves info about one item in the current retrieved list of items from the Auction House.
local name, texture, count, quality, canUse, level, levelColHeader, minBid,
    minIncrement, buyoutPrice, bidAmount, highBidder, bidderFullName, owner,
    ownerFullName, saleStatus, itemId, hasAllInfo = GetAuctionItemInfo("type", index)


name, texture, ... = GetAuctionItemInfo("type", index);
== Parameters ==
 
=== Arguments ===
----
:;type
;''Arguments''
:: String - One of the following:
:(String type, Number index)
:::*"list" - An item up for auction, the "Browse" tab in the dialog.
 
:::*"bidder" - An item the player has bid on, the "Bids" tab in the dialog.
:;type : One of the following:
:::*"owner" - An item the player has up for auction, the "Auctions" tab in the dialog.
:::;"list" : An item up for auction, the "Browse" tab in the dialog.
:;index
:::;"bidder" : An item the player has bid on, the "Bids" tab in the dialog.
:: Integer - The index of the item in the list to retrieve info from (normally 1-50, inclusive)
:::;"owner" : An item the player has up for auction, the "Auctions" tab in the dialog.
=== Returns ===
 
:;name
:;index : The index of the item in the list to retrieve info from (normally 1-50, inclusive)
:: (string) the name of the item
 
:;texture
----
:: (string) the name of the texture of the item
;''Returns''
:;count
:: (number) the amount of items in the auction item, zero if item is "sold" in the "owner" auctions
:;quality
:: (number) an index into the [[API ITEM_QUALITY_COLORS|ITEM_QUALITY_COLORS]] array
:;canUse
:: (boolean) true if the user can use the item, false if not
:;level
:: (number) the level required to use the item
:;levelColHeader
:: unknown
:;minBid
:: (number) the starting bid price
:;minIncrement
:: (number) the minimum amount of item at which to put the next bid
:;buyoutPrice
:: (number) zero if no buy out, otherwise it contains the buyout price of the auction item
:;bidAmount
:: (number) the current highest bid, zero if no one has bid yet
:;highBidder
:: (boolean) true if the current player is the highest bidder, otherwise nil
:;bidderFullName
:: (string) the full name of the highest bidder if in the same [[Connected Realm]], otherwise nil (added 5.4.0)
:;owner
:: the player that is selling the item
:;ownerFullName
:: (string) the full name of the owner if in the same [[Connected Realm]], otherwise nil (added 5.4.0)
:;saleStatus
:: 1 for sold 0 for unsold
:;itemId
:: (number) the item id
:;hasAllInfo
:: (boolean) true if all infos where retrieved


:;name : a string containing the name of the item
== Example ==
:;texture : a string containing the name of the texture of the item
local name, texture, count, quality, canUse, level, levelColHeader, minBid, minIncrement,
:;count : a number containing the number of items in the auction item
  buyoutPrice, bidAmount, highBidder, highBidderFullName, owner, ownerFullName,
:;quality : an index into the [[API ITEM_QUALITY_COLORS|ITEM_QUALITY_COLORS]] array
  saleStatus, itemId, hasAllInfo = GetAuctionItemInfo("owner", 1);
:;canUse : a boolean, true if the user can use the item, false if not
:;level : a number referring to the level required to use the item
:;minBid : the starting bid price
:;minIncrement : the minimum amount of item at which to put the next bid
:;buyoutPrice : zero if no buy out, otherwise it contains the buyout price of the auction item
:;bidAmount : the current highest bid, zero if no one has bid yet
:;highBidder : a boolean that is true if the current player is the highest bidder, otherwise nil
:;owner : the player that is selling the item


----
Retrieves info about the first item in the list of your currently auctioned items.
;''Example''
name, texture, count, quality, canUse, level,
minBid, minIncrement, buyoutPrice, bidAmount,
highBidder, owner = GetAuctionItemInfo("owner", offset + i);


;''Result''
== Details ==
Note that the 'owner' field can be 'nil'. This happens because the auction listing internally contains player GUIDs rather than names, and the WoW client does not query the server for names until GetAuctionItemInfo is actually called for the item, and the result takes one [[RTT]] to arrive. The 'GUID to name' mapping is then stored in a name resolution cache, which gets cleared upon log-out, not UI reload.


Retrieves info about an item in the current list of auction items. Affects nothing other than the return values.
Blizzard's standard auction house view overcomes this problem by reacting to AUCTION_ITEM_LIST_UPDATE and re-querying the items.


----
However, this event-driven approach does not really work for e.g. scanner engines. There, the correct solution is to re-query items with nil owners for a short time (a low number of seconds). There IS a possibility that it NEVER returns something - this happens when someone puts something up for auction and then deletes his character.
;''Description''


: Retrieves info about an item in the current list of auction items.
Also note that these GUID-to-name queries cause client-to-server bandwidth; 14 bytes each (in 2.3.2). For a normal 50-item page this is of course negligeable, but for a full-AH scan on a medium-size server, you easily generate enough traffic to disconnect yourself if you do not throttle the rate at which you send queries. See [[ChatThrottleLib]] for information on client-to-server bandwidth.


----
== Notes ==
{{Template:WoW API}}
* 'bidderFullName' and 'ownerFullName' return values were added {{Patch 5.4.0|t=inline}}, in order to support [[Connected Realms]].

Latest revision as of 04:45, 15 August 2023

WoW API < GetAuctionItemInfo

Retrieves info about one item in the current retrieved list of items from the Auction House.

local name, texture, count, quality, canUse, level, levelColHeader, minBid,
    minIncrement, buyoutPrice, bidAmount, highBidder, bidderFullName, owner,
    ownerFullName, saleStatus, itemId, hasAllInfo = GetAuctionItemInfo("type", index)

Parameters[edit]

Arguments[edit]

type
String - One of the following:
  • "list" - An item up for auction, the "Browse" tab in the dialog.
  • "bidder" - An item the player has bid on, the "Bids" tab in the dialog.
  • "owner" - An item the player has up for auction, the "Auctions" tab in the dialog.
index
Integer - The index of the item in the list to retrieve info from (normally 1-50, inclusive)

Returns[edit]

name
(string) the name of the item
texture
(string) the name of the texture of the item
count
(number) the amount of items in the auction item, zero if item is "sold" in the "owner" auctions
quality
(number) an index into the ITEM_QUALITY_COLORS array
canUse
(boolean) true if the user can use the item, false if not
level
(number) the level required to use the item
levelColHeader
unknown
minBid
(number) the starting bid price
minIncrement
(number) the minimum amount of item at which to put the next bid
buyoutPrice
(number) zero if no buy out, otherwise it contains the buyout price of the auction item
bidAmount
(number) the current highest bid, zero if no one has bid yet
highBidder
(boolean) true if the current player is the highest bidder, otherwise nil
bidderFullName
(string) the full name of the highest bidder if in the same Connected Realm, otherwise nil (added 5.4.0)
owner
the player that is selling the item
ownerFullName
(string) the full name of the owner if in the same Connected Realm, otherwise nil (added 5.4.0)
saleStatus
1 for sold 0 for unsold
itemId
(number) the item id
hasAllInfo
(boolean) true if all infos where retrieved

Example[edit]

local name, texture, count, quality, canUse, level, levelColHeader, minBid, minIncrement,
  buyoutPrice, bidAmount, highBidder, highBidderFullName, owner, ownerFullName,
  saleStatus, itemId, hasAllInfo = GetAuctionItemInfo("owner", 1);

Retrieves info about the first item in the list of your currently auctioned items.

Details[edit]

Note that the 'owner' field can be 'nil'. This happens because the auction listing internally contains player GUIDs rather than names, and the WoW client does not query the server for names until GetAuctionItemInfo is actually called for the item, and the result takes one RTT to arrive. The 'GUID to name' mapping is then stored in a name resolution cache, which gets cleared upon log-out, not UI reload.

Blizzard's standard auction house view overcomes this problem by reacting to AUCTION_ITEM_LIST_UPDATE and re-querying the items.

However, this event-driven approach does not really work for e.g. scanner engines. There, the correct solution is to re-query items with nil owners for a short time (a low number of seconds). There IS a possibility that it NEVER returns something - this happens when someone puts something up for auction and then deletes his character.

Also note that these GUID-to-name queries cause client-to-server bandwidth; 14 bytes each (in 2.3.2). For a normal 50-item page this is of course negligeable, but for a full-AH scan on a medium-size server, you easily generate enough traffic to disconnect yourself if you do not throttle the rate at which you send queries. See ChatThrottleLib for information on client-to-server bandwidth.

Notes[edit]