auction system api.pdf

Company Title Registration number

External Project Entropia Auction script API Revision Page

PA1 1(12)Author Subject Update date

Johan Wolff 2003-04-01

Created Saved Printed Document name Title Page

02-11-05 10:43 03-04-08 21:12 14-02-17 18:37 D:\Fraps\Oblivion 2\Old Auction and Society Documents\auction andsociety\auction\Dokument\Auction System API.doc

External Auction System script API 1 (12)

MA Small v1.7

External Project Entropia Auction script API

IntroductionToday there is no support for inter-player trade. The players have solved this by unattached PEweb pages and very annoying public advertisements of items for sale. By providing this functionwithin PE, we will centralize PE-attached activity and remove possibilities of trade fraud.








MA Small v1.7

Content

EXTERNAL PROJECT ENTROPIA AUCTION SCRIPT API............................................ 1

Introduction........................................................................................................................ 1Content ............................................................................................................................... 2

FUNCTIONS ............................................................................................................................. 3AuctionCreateAuctionItem.................................................................................................. 3AuctionDeleteAuctionItem .................................................................................................. 3AuctionPlaceBid ................................................................................................................. 3AuctionSearchItem.............................................................................................................. 4AuctionGetAuctionItem....................................................................................................... 4AuctionGetAuctionItemHistory ........................................................................................... 5AuctionPlayerAuctions ....................................................................................................... 5AuctionGetLatestAuctionItems............................................................................................ 5AuctionStartUp ................................................................................................................... 5AuctionCloseDown ............................................................................................................. 6

EVENTS................................................................................................................................... 7OnAuctionCreateAuctionItem ............................................................................................. 7OnAuctionDelete ................................................................................................................ 7OnAuctionPlaceBid ............................................................................................................ 7OnAuctionSearchItem......................................................................................................... 8OnAuctionAuctionItemInfo.................................................................................................. 8OnAuctionGetAuctionItemHistory....................................................................................... 9OnAuctionPlayerAuctions................................................................................................... 9OnAuctionLatestAuctionItems............................................................................................. 9OnAuctionStartUp ............................................................................................................ 10OnAuctionAuctionUpdate ................................................................................................. 10OnAuctionLoadInstance.................................................................................................... 11

DOCUMENT HISTORY ............................................................................................................. 12History.............................................................................................................................. 12








MA Small v1.7

Functions

AuctionCreateAuctionItemvoid AuctionCreateAuctionItem(int iPlayerId, int iItemId, int iValidDays, int iStartPrice, intiBuyOutPrice, int iCategory)

ParameteriPlayerId Id of playeriItemId Id of itemiValidDays Number of days the auction is validiStartPrice Start price of the auction item (the total price if more than one item is for

sale)iBuyOutPrice The auction ends and a transaction is made if this price is metiCategory Category of item

ReceiptThe event OnAuctionCreateAuctionItem is sent back with an id of the auction item.

DescriptionCreate a new auction item. An auction cannot be active for more than seven days. If the biddermatched the buy out price, then is the auction closed and a transaction is made. Set iBuyOutPriceto –1 if no such price should exist. The player can only sell items from his inventory, i.e. itemsthat he is carrying. There is a limit of not more than five auction items per player. The player canonly sell one item per auction.

AuctionDeleteAuctionItemvoid AuctionDeleteAuctionItem(int iPlayerId, int iAuctionItem)

ParameteriPlayerId Id of playeriAuctionItem Id of an auction item created with AuctionCreateAuctionItem()

ReceiptThe event OnAuctionDelete is sent back.

DescriptionDelete an active auction item. All items are moved from deposition to the player’s carriedinventory. A player can only delete one of his own auction items. An auction item can only bedeleted if there are no bids on it.

AuctionPlaceBidvoid AuctionPlaceBid(int iPlayerId, int iAuctionItem, int iBidPrice)








MA Small v1.7

ParameteriPlayerId Id of player placing the bidiAuctionItem Id of an auction item created with AuctionCreateAuctionItem()iBidPrice The player’s bid

ReceiptThe event OnAuctionPlaceBid is sent back.

DescriptionPlace a bid for a player. If a bid is placed within five minutes of the closing time, then theclosing time is being extended with five minutes.

AuctionSearchItemvoid AuctionSearchItem(int iPlayerId, int iCategory, int iStart, int iNbrOfHits)

ParameteriPlayerId Id of playeriCategory Id of categoryiStart Start of hit listiNbrOfHits Limit the search to iNbrOfHits hits

ReceiptThe event OnAuctionSearchItem is sent back for every hit.

DescriptionSearch for a group of items in the PE Auction. Use parameter iNbrOfHits to limit the number ofhits, i.e. events sent back to the client. Parameter iStart can be used to retrieve chunks of hits, e.g.if iNbrOfHits is set to 20 and a search results in 37 hits; set iStart to 0 for the first 20 hits andiStart to 21 for the remaining 17 hits. If iNbrOfHits is set to –1, then all search hits are sent back.

AuctionGetAuctionItemvoid AuctionGetAuctionItem(int iPlayerId, int iAuctionItem)

ParameteriPlayerId Id of player placing the bidiAuctionItem Id of an auction item created with AuctionCreateAuctionItem()

ReceiptThe event OnAuctionAuctionItemInfo is sent back.

DescriptionGet information about a specific auction item.








MA Small v1.7

AuctionGetAuctionItemHistoryvoid AuctionGetAuctionItemHistory(int iPlayerId, int iAuctionItem, int iStart, int iNbrOfBids)

ParameteriPlayerId Id of player placing the bidiAuctionItem Id of an auction item created with AuctionCreateAuctionItem()iStart Start of hit listiNbrOfBids Get only iNbrOfBids bids

ReceiptThe event OnAuctionGetAuctionItemHistory is sent back for every auction item.

DescriptionGet auction history for a specific auction item. Set parameter iNbrOfBids to –1 if all bids shouldbe received. Parameter iStart works exactly like the iStart parameter in functionAuctionSearchItem (see above).

AuctionPlayerAuctionsvoid AuctionPlayerAuctions(int iPlayerId)

ParameteriPlayerId Id of player

ReceiptThe event OnAuctionPlayerAuctions is sent for each and every auction item.

DescriptionGet all active auction items for a player.

AuctionGetLatestAuctionItemsvoid AuctionGetLatestAuctionItems(int iPlayerId)


ReceiptThe event OnAuctionLatestAuctionItems is sent back.

DescriptionGet the ten latest created auction items.

AuctionStartUpvoid AuctionStartUp(int iPlayerId)








MA Small v1.7


ReceiptThe event OnAuctionStartUp is sent back.

DescriptionThis function is called when a player open the auction interface, the function report to the playerif any auctions has been closed since the last time the interface was open (auction items theplayer owned or had a bid on). The following checks are made:

· If the player had the highest bid and won the auction, then the item is transferred to theplayer’s inventory.

· If the player is no longest the highest bidder, he will be giving a chance to place a newbid. The player will receive his deposit.

· If the player had an auction that was closed, money is added to the player’s accountbalance.

· If an auction has been marked invalid due to passed end date (and no player has placed abid), then the item is moved from the deposition to the player’s carried inventory.

Money and items are not transferred to the players’ accounts and inventories until theplayers opens the auction interface, even if the auction has already been committed.

AuctionCloseDownvoid AuctionCloseDown(int iPlayerId)


ReceiptNo receipt is sent back.

DescriptionCall this function when a player closes down the PE Auction interface. This function is used toupdate an internal list in the server of users that have the auction interface open. The purpose isto know which users to send event to when an auction item has be altered, e.g. new highest bid.








MA Small v1.7

EventsAll events are sent to the client except for OnAuctionLoadInstance, which is sent to the server.

OnAuctionCreateAuctionItemOnAuctionCreateAuctionItem(int iAuctionItem)

ParametersiAuctionItem Id of newly created auction item

DescriptionThis event is sent back when a new auction item has been created. iAuctionItem is -1 if an errorhas occurred and 0 if the player already have five auctions (an auction item is not created in thatcase).

OnAuctionDeleteOnAuctionDelete(int iResult)

ParametersiResult Id of the item that was deleted, –1 if an error occurred and 0 if the

removal couldn’t be made because there are bidders on the auction

DescriptionThis event is sent back when function AuctionDeleteAuctionItem is called. An auction can onlybe deleted if there are no bidders.

OnAuctionPlaceBidOnAuctionPlaceBid(int iAuctionItem, int iStatus)

ParametersiAuctionItem Id of auction itemiStatus Status of bid

DescriptionThis event is sent when the function AuctionPlaceBid is called. The status flag can have thefollowing values:

iStatus Description-1 On error occurred, the bid has been cancelled.0 Bid has been accepted and the player has the current highest bid.2 Bid lower than start price3 The bid is not higher than the current highest








MA Small v1.7

4 Bid has been accepted and the auction has ended since the playermatched the buy out price.

5 The bid was placed too late, auction already ended6 The player owns the auction7 The player has the current highest bid8 The player does not have enough PED to place in deposition

CommentsIf the player has the current highest bid, i.e. iStatus is 0, then the amount specified in functioncall AuctionPlaceBid has been moved to a deposition. If iStatus is 4, then a transaction has beenmade and the player will have the item in his inventory, the player’s account is decreased withthe correct amount.

OnAuctionSearchItemOnAuctionSearchItem(string sItem, string sCloseDate, int iAuctionItem, int iCurrentPrice, intiBids)

ParameterssItem Name of itemsCloseDate Date until the auction is closediAuctionItem Id of auction item (e.g. used when deleting)iCurrentPrice Current bid priceiBids Number of bids since the auction started

DescriptionThis event is sent back when the function AuctionSearchItem is called. One event is sent foreach search match. Checks must be made to see if more than one event has same iAuctionItemvalue. If that is the case, then that auction item contain more than one item. The last event hasthe values OnAuctionSearchItem(“”, “”, 0, 0, 0).

OnAuctionAuctionItemInfoOnAuctionAuctionItemInfo(int iAuctionItem, int iItemId, int iAgdaClass, int iTTValue, intiStartBid, string sItem, string sSeller, string sStartDate, string sCloseDate)

ParametersiAuctionItem Id of auction item (e.g. used when deleting)iItemId Id of item for saleiAgdaClass Agda class idiTTValue Trade terminal value of itemiStartBid Start bidsItem Name of item for salesSeller name of sellersStartDate Date when the auction item startedsCloseDate Date until the auction item is closed

Description








MA Small v1.7

Gather information about an single auction item.

OnAuctionGetAuctionItemHistoryOnAuctionGetAuctionItemHistory(string sBidder, string sBidDate, int iPrice)

ParameterssBidder Name of biddersBidDate Date and time when the bid was madeiPrice The bidder’s price

DescriptionThis event is received when function AuctionGetAuctionItemHistory is called. One event is sentfor every bidding action. The last event is OnAuctionGetAuctionItemHistory(“”, “”, 0),indicating no more events.

OnAuctionPlayerAuctionsOnAuctionPlayerAuctions(int iAuctionItem, int iStartBid, int iBids, int iCurrentBid, intiDummy, string sItem, string sStartDate, string, sCloseDate, int iDummy)

ParametersiAuctionItem Id of auction item (e.g. used when deleting)iStartBid Start price of auction itemiBids Number of bids since auction startediCurrentBid Current bid priceiDummy Dummy variable set to 0sItem Name of item for salesStartDate Date when the auction startedsCloseDate Date until the auction is closediDummy Dummy variable set to 0

DescriptionThis event is sent back when the function AuctionPlayerItems is called. One event is sent foreach active auction the player has. Checks must be made to see if more than one event has sameiAuctionItem value. If that is the case, then that auction item contain more than one item. Thelast event is OnAuctionActivePlayerAuctions(0, 0, 0, 0, 0, “”, “”, “”, 0).

OnAuctionLatestAuctionItemsOnAuctionLatestAuctionItems(string sItem, string sCloseDate, int iAuctionItem, intiCurrentPrice, int iBids, int iItemId)

ParameterssItem Name of itemsCloseDate Date until the auction is closediAuctionItem Id of auction itemiCurrentPrice Current bid price








MA Small v1.7

iBids Number of bids since the auction startediItemId Id of item for sale

DescriptionOne event is sent for at most 10 auction items. Checks must be made to see if more than oneevent has same iAuctionItem value. If that is the case, then that auction item contain more thanone item. The last event has the values OnAuctionLatestAuctionItems(“”, “”, 0, 0, 0, 0).

OnAuctionStartUpOnAuctionStartUp(int iAuctionItem, int iItemId, int iAction, int iPrice, string sItem)

ParametersiAuctionItem Id of auction itemiItemId Id of itemiAction See belowiPrice Total pricesItem Name of item in auction

DescriptionThis event is sent when function AuctionStartUp is being called. Parameter iAction can have thefollowing values:

iAction Description-1 Error. Auction temporarily unavailable0 Auction has been closed, money is transferred to the player’s account balance1 An auction has been closed and the player had the highest bid, item is moved to

player’s inventory2 The player does no longer have the highest bid, money is moved back from

deposition to the account balance3 Auction has been closed, but no bid was placed (item is moved back to the player’s

inventory)

Checks must be made to see if more than one event has same iAuctionItem value. If that is thecase, then that auction item contain more than one item. As with case of the functionAuctionCreateAuctionItem, the iPrice parameter represents the price of the entire auction item,not single items within the auction. The last event sent is OnAuctionStartUp(0, 0, “”, 0).

OnAuctionAuctionUpdateOnAuctionAuctionUpdate(int iMainCategory, int iCategory)

ParametersiMainCategory Id of main categoryiCategory Id of category

Description








MA Small v1.7

This event is sent to all players that have logged on to the PE Auction. A player is logged onwhen he have called function AuctionStartUp, the player must log of with functionAuctionCloseDown. The event is sent in the following cases:

· An auction item has been closed· An auction item has been deleted· An auction item has a new highest bidder (and maybe extended stop time)· An new auction item has been created

This event is currently not implemented.

OnAuctionLoadInstanceOnAuctionLoadInstance(int iItemId, int iPlayerId)

ParametersiItemId Id of instance (item)iPlayerId Id of player (mind id)

DescriptionThis event is sent to the server just before events OnAuctionLatestAuctionItems andOnAuctionAuctionItemInfo are sent to the client. The event is a confirmation that one or severalinstances have been loaded into memory on the server. Even though eventOnAuctionLatestAuctionItems can contain up to 20 items/instances, this event is sent only once.








MA Small v1.7

Document history

HistoryCopy the top empty row and past it on the same row, so there always is an empty line at the top.If you need more than one line for your description just keep on writing in the same cell.The history table shall be in reversed chronological order.

Date Event Ver Sign

2003-04-01 The event OnAuctionLoadInstance 1.5 JW2003-03-21 New function headers 1.4 JW2003-03-18 New function and event; AuctionGetItemCategory and

OnAuctionItemCategory. New parameter list for functionAuctionSearchItem.

1.3 JW

2003-03-13 New status flag in event OnAuctionPlaceBid 1.2 JW2003-03-04 New functions AuctionGetLatestAuctionItems and

AuctionCloseDown. New event OnAuctionAuctionUpdate.1.1 JW

2003-03-03 Document created 1.0 JW