Auctioneer/5.0/Modules API

Norganna's AddOns

Modules in Auctioneer can be of one of three kinds

• Statistics Modules
• Utility Modules
• Filter Modules

Auctioneer takes care of loading modules whether they are embedded or not (more on this later). Auctioneer requires that all modules follow the "Auc-Type-Name" naming convention. Where type is one of "Stats", "Util", or "Filter" depending on the type of module, and Name is chosen by the author. Auctioneer requires that this name be used as both the folder's name and as the internal module name. Some functions will be passed this name as the first argument when called from Auctioneer, so its individuality is a must.

Auctioneer also requires that every module add a table of functions to one and only one of the following three locations depending on the type of module that it is. {{#funcdef: AucAdvanced.Modules.Stats}} or {{#funcdef: AucAdvanced.Modules.Util}} or {{#funcdef: AucAdvanced.Modules.Filter}}.

The aforementioned table of functions can include any of the following functions.

목차 1 All Modules 2 Statistics Modules 3 Utilities Modules 4 Filter Modules

All Modules

{{#funcdef: GetName() -- This function is required! This function returns the name of the module, for example if the full module's name is "Auc-Util-Example", this function should return "Example". }}{{#funcdef: OnLoad(addon) Auctioneer will call this function when your module's variables are loaded by the game. Passes the addon name. You can register your interest in being notified of other AddOns than your own by placing an entry for that AddOn's name in your {{#funcdef: LoadTriggers}} table. }}{{#funcdef: Processor(callbackType, ...) This function is the generic message handler. Auctioneer will call this function whenever it has something to communicate to the module. Example callback types are:

• "auctionui"
  Called to inform the module that the auction house has been loaded.
• "auctionopen"
  Called each time the auction house is opened.
• "auctionclose"
  Called each time the auction house is closed.
• "load", addon
  Called whenever an Auctioneer module loads.
• "tooltip", frame, name, hyperlink, quality, quantity, cost, additional
  Called to give the module a chance to display tooltip information.
• "listupdate"
  Called whenever the auction house browse list is updated.
• "config", gui
  Called when the GUI config is first opened to give you the chance to add your configuration parameters to it. Supplies the Gui object as the first parameter.
• "configchanged", setting, value
  Called whenever a parameter is updated in the configuration. Passes the setting name and the new value as parameters.
• "inventory"
  Fired when there's an inventory change.
• "scanstats", stats
  A scan or other change has completed and scan data and stats are updated. You should clear all your cached stats. Pricing functions should not be called from within this message handler. Passes statistics about the scan, and what was updated.
• "scanprogress", state, totalAuctions, scannedAuctions
  Called when the progress of a scan has been changed. The state parameter will be true if we want to show the process indicator, false if we want to hide it and nil if we only want to update it. The totalAuctions parameter will be a number that is the max number of items in the scan and the scannedAuctions parameter is the current progress of the scan.
• "pagefinished", pageNumber
  Called when AucAdv is done with a page, allowing modules to work with it.
• "postresult", success, id, request, [error]
  Whenever a queued post has succeeded or failed, this callback will be called. The success flag will be set to either true or false, depending on if the post was made or not. The postId is one of the postIds that was returned in a table from the {{#funcdef: AucAdvanced.Post.PostAuction(sig, size, bid, buyout, duration, multiple)}} function. The request parameter contains the detail of the post in a table like: {sig, size, bid, buyout, duration}. The error message is passed if there was an error and contains the text of the error.
• "bidplaced", auctionstring
  Called whenever a bid has been successfully placed. Auctionstring is "itemlink;seller;count;buyout;pricepaid;reason"

}}{{#funcdef: CommandHandler(...) This function is used to pass along any slash commands pertaining to your module. Passes the remainder of the entered command, split at spaces. }}{{#funcdef: ScanProcessors {} This table of functions is used to receive messages from the scanning module. If you want to store stats about the items as they are scanned, you should place entries in this table with the key equal to one of the below message types and pointers to the function that you want to process that data as the values. The possible messages that can be sent to your module are:

• "begin"
  Sent when the scanner is about to send a batch of data. Initializing once-per-scan variables here is a good idea instead of redoing them for every single item.
• "update", newitem, olditem
  An existing item has been changed.
• "leave", olditem
  An existing item that still exists and has not changed.
• "create", newitem
  A new item has been found which did not exist prior to the scan.
• "delete", olditem
  An item that existed prior to the scan now does not exist.
• "placebid", listitem, listtype, index, bid
  A bid has been placed. Refer to documentation for {{#funcdef: PlaceAuctionBid(listtype, index, bid)}}.
• "newauc", newitem, statItem, minBid, buyoutPrice, runTime, price
  A new auction has been posted.
• "aucsold", faction, itemName, playerName, bid, buyout, deposit, consignment
  Money has been received in the mail from the sale of an auction.
• "complete"
  The batch has completed, you may now cleanup / process / store any accumulated data.

}}{{#funcdef: LoadTriggers {} A table of interesting AddOns to your module. Whenever an AddOn loads that has a key in this table, your {{#funcdef: OnLoad(addon)}} function will be called with that AddOn's name. Note: All AddOn's names should be entered into this table in lowercase}}

Statistics Modules

Statistics modules collect and create statistic data, and their statistic data is used to provide market pricing data via the API function {{#funcdef: AucAdvanced.API.GetMarketValue(itemLink, serverKey)}}. {{#funcdef: GetPrice(itemLink, serverKey) This function returns a series of values the most accurate/relevant/recent price is the first value returned other less relevant prices are returned in order of most relevant, to least relevant then a false value is returned then other "interesting" values are returned thereafter.

A statistic module's GetPrice() function can be accessed by other addons via AucAdvanced.GetModule("moduletype", "modulename").GetPrice(itemlink). ie-AucAdvanced.GetModule("Stat", "Simple").GetPrice(itemlink) for the Simple stat.

}}{{#funcdef: GetPriceColumns() This function returns the respective "names" of the values returned by {{#funcdef: GetPrice(itemLink, serverKey)}} }}{{#funcdef: GetPriceArray(itemLink, serverKey) This function is a combination of the above two functions, and returns it's values in a table. Three of the keys that are expected to be in this table are "price", "seen", and "confidence", being the best price, the seen count, and a confidence value (0.00-1.00). Other values may be provided by the AddOn in other fields.}} {{#funcdef: GetItemPDF(hyperlink, serverKey) This function returns a probability distribution function (PDF) which indicates the module's determined probability of a price value for the item. The function returned should accept one parameter, the price of the item, and return a value from 0 to 1 indicating the probability of that price to be the true price. The area under the curve should be 1 in most cases, though any finite value is allowed, but will have the side effect of a weight against other modules (i.e., a function with an area of 5 will count 5 times as much as a function with an area of 1). The API function {{#funcdef: AucAdvanced.API.GenerateBellCurve()}} can provide the standard normal distribution as a common PDF (the bell curve).

The following return values must be supplied, in order:

• The Item PDF, either as a closure or as a value with a __call metamethod. The prototype must be "p = pdf(x)" where x is the item value, in copper, of the price being tested, and p is the probability (1 = 100%, 0.5 = 50%, etc.) that the specified value of x is correct.
• The lower limit of integration (below this value for x, values are negligible). Warning: Depending on conditions, the integrator may decide to test below this value if it feels it is worth testing. Your function MUST still return a value, even if it is just 0, for values below the lower limit.
• The upper limit of integration (above this value for x, values are negligible). Warning: Depending on conditions, the integrator may decide to test above this value if it feels it is worth testing. Your function MUST still return a value, even if it is just 0, for values above the upper limit.
• The total area under the curve. (Optional) Defaults to 1.

}}Occasionally, data for an item needs to be cleared. The API function {{#funcdef: AucAdvanced.API.ClearItem(itemLink, serverKey)}} will call for each stat module: {{#funcdef: ClearItem(itemLink, serverKey) This function tells the statistics module to clear data for the linked item.}}

Utilities Modules

Utilities modules are no less flexible than statistics modules and may provide whatever functions they need to provide, even to the extent of providing pricing functions like the above statistics modules. Prices provided by a Utility module will not be used for the market value supplied by the {{#funcdef: AucAdvanced.API.GetMarketValue(itemLink, serverKey)}} function. If it does provides pricing function, it will however appear in the list generated by {{#funcdef: AucAdvanced.API.GetAlgorithms()}} and be queryable via the {{#funcdef: AucAdvanced.API.GetAlgorithmValue(algorithm, itemLink, serverKey)}} function. It may be a good idea to place derivative statistics or abstract statistics functions in as utilities in order to avoid polluting the market value data with crazy prices. Generally utility modules will have a more interactive nature than statistics modules, providing UI functionality and/or abstract (non-price related) statistical data.

Filter Modules

Filter modules provide the core filtering to prevent items or prices from entering the DB. They help to cut down on database size and in some cases although to a lesser extent, price pollution. Filter modules should (but are not required to) have the function {{#funcdef:AuctionFilter(operation, itemData) This function filters based on the information in itemData. itemData is a table containing all of the Auctioneer information about an item, including information available through the default tooltips, as well as information such as the last time it was seen, and how many times it has been seen.}}