diff --git a/src/game/Mail.cpp b/src/game/Mail.cpp index b2ae271ad..4bd864227 100644 --- a/src/game/Mail.cpp +++ b/src/game/Mail.cpp @@ -16,6 +16,15 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ +/** + * @addtogroup mailing + * @{ + * + * @file Mail.cpp + * This file contains the the code needed for MaNGOS to handle mails. + * + */ + #include "Mail.h" #include "WorldPacket.h" #include "WorldSession.h" @@ -32,16 +41,34 @@ #include "BattleGroundMgr.h" #include "Item.h" #include "AuctionHouseMgr.h" - +/** + * Flags that specify special action to be take by the client when displaying this mail. + */ enum MailShowFlags { MAIL_SHOW_UNK0 = 0x0001, - MAIL_SHOW_DELETE = 0x0002, // forced show delete button instead return button - MAIL_SHOW_AUCTION = 0x0004, // from old comment - MAIL_SHOW_UNK2 = 0x0008, // unknown, COD will be shown even without that flag + MAIL_SHOW_DELETE = 0x0002, ///< forced show of the delete button instead of the return button + MAIL_SHOW_AUCTION = 0x0004, ///< from old comment + MAIL_SHOW_UNK2 = 0x0008, ///< unknown, COD will be shown even without that flag MAIL_SHOW_RETURN = 0x0010, }; - +/** + * Handles the Packet sent by the client when sending a mail. + * + * This methods takes the packet sent by the client and performs the following actions: + * - Checks whether the mail is valid: i.e. can he send the selected items, + * does he have enough money, etc. + * - Creates a MailDraft and adds the needed items, money, cost data. + * - Sends the mail. + * + * Depending on the outcome of the checks performed the player will recieve a different + * MailResponseResult. + * + * @see MailResponseResult + * @see SendMailResult() + * + * @param recv_data the WorldPacket containing the data sent by the client. + */ void WorldSession::HandleSendMail(WorldPacket & recv_data ) { uint64 mailbox, unk3; @@ -265,7 +292,17 @@ void WorldSession::HandleSendMail(WorldPacket & recv_data ) CharacterDatabase.CommitTransaction(); } -//called when mail is read +/** + * Handles the Packet sent by the client when reading a mail. + * + * This method is called when a client reads a mail that was previously unread. + * It will add the MAIL_CHECK_MASK_READ flag to the mail being read. + * + * @see MailCheckMask + * + * @param recv_data the packet containing information about the mail the player read. + * + */ void WorldSession::HandleMailMarkAsRead(WorldPacket & recv_data ) { uint64 mailbox; @@ -289,7 +326,14 @@ void WorldSession::HandleMailMarkAsRead(WorldPacket & recv_data ) } } -//called when client deletes mail +/** + * Handles the Packet sent by the client when deleting a mail. + * + * This method is called when a client deletes a mail in his mailbox. + * + * @param recv_data The packet containing information about the mail being deleted. + * + */ void WorldSession::HandleMailDelete(WorldPacket & recv_data ) { uint64 mailbox; @@ -317,7 +361,15 @@ void WorldSession::HandleMailDelete(WorldPacket & recv_data ) } pl->SendMailResult(mailId, MAIL_DELETED, MAIL_OK); } - +/** + * Handles the Packet sent by the client when returning a mail to sender. + * This method is called when a player chooses to return a mail to its sender. + * It will create a new MailDraft and add the items, money, etc. associated with the mail + * and then send the mail to the original sender. + * + * @param recv_data The packet containing information about the mail being returned. + * + */ void WorldSession::HandleMailReturnToSender(WorldPacket & recv_data ) { uint64 mailbox; @@ -375,7 +427,9 @@ void WorldSession::HandleMailReturnToSender(WorldPacket & recv_data ) pl->SendMailResult(mailId, MAIL_RETURNED_TO_SENDER, MAIL_OK); } -//called when player takes item attached in mail +/** + * Handles the packet sent by the client when taking an item from the mail. + */ void WorldSession::HandleMailTakeItem(WorldPacket & recv_data ) { uint64 mailbox; @@ -470,7 +524,9 @@ void WorldSession::HandleMailTakeItem(WorldPacket & recv_data ) else pl->SendMailResult(mailId, MAIL_ITEM_TAKEN, MAIL_ERR_EQUIP_ERROR, msg); } - +/** + * Handles the packet sent by the client when taking money from the mail. + */ void WorldSession::HandleMailTakeMoney(WorldPacket & recv_data ) { uint64 mailbox; @@ -504,7 +560,10 @@ void WorldSession::HandleMailTakeMoney(WorldPacket & recv_data ) CharacterDatabase.CommitTransaction(); } -//called when player lists his received mails +/** + * Handles the packet sent by the client when requesting the current mail list. + * It will send a list of all avaible mails in the players mailbox to the client. + */ void WorldSession::HandleGetMailList(WorldPacket & recv_data ) { uint64 mailbox; @@ -632,7 +691,12 @@ void WorldSession::HandleGetMailList(WorldPacket & recv_data ) _player->UpdateNextMailTimeAndUnreads(); } -///this function is called when client needs mail message body, or when player clicks on item which has ITEM_FIELD_ITEM_TEXT_ID > 0 +/** + * Handles the packet sent by the client when requesting information about the body of a mail. + * + * This function is called when client needs mail message body, + * or when player clicks on item which has ITEM_FIELD_ITEM_TEXT_ID > 0 + */ void WorldSession::HandleItemTextQuery(WorldPacket & recv_data ) { uint32 itemTextId; @@ -641,7 +705,7 @@ void WorldSession::HandleItemTextQuery(WorldPacket & recv_data ) recv_data >> itemTextId >> mailId >> unk; - //some check needed, if player has item with guid mailId, or has mail with id mailId + ///TODO: some check needed, if player has item with guid mailId, or has mail with id mailId sLog.outDebug("CMSG_ITEM_TEXT_QUERY itemguid: %u, mailId: %u, unk: %u", itemTextId, mailId, unk); @@ -651,7 +715,13 @@ void WorldSession::HandleItemTextQuery(WorldPacket & recv_data ) SendPacket(&data); } -//used when player copies mail body to his inventory +/** + * Handles the packet sent by the client when he copies the body a mail to his inventory. + * + * When a player copies the body of a mail to his inventory this method is called. It will create + * a new item with the text of the mail and store it in the players inventory (if possible). + * + */ void WorldSession::HandleMailCreateTextItem(WorldPacket & recv_data ) { uint64 mailbox; @@ -719,9 +789,12 @@ void WorldSession::HandleMailCreateTextItem(WorldPacket & recv_data ) } } -//TODO Fix me! ... this void has probably bad condition, but good data are sent -void WorldSession::HandleQueryNextMailTime(WorldPacket & /*recv_data*/ ) +/** + * No idea when this is called. + */ +void WorldSession::HandleQueryNextMailTime(WorldPacket & /**recv_data*/ ) { + //TODO Fix me! ... this void has probably bad condition, but good data are sent WorldPacket data(MSG_QUERY_NEXT_MAIL_TIME, 8); if( _player->unReadMails > 0 ) @@ -773,6 +846,12 @@ void WorldSession::HandleQueryNextMailTime(WorldPacket & /*recv_data*/ ) SendPacket(&data); } +/** + * Creates a new MailSender object. + * + * @param sender The object/player sending this mail. + * @param stationery The stationary associated with this sender. + */ MailSender::MailSender( Object* sender, MailStationery stationery ) : m_stationery(stationery) { switch(sender->GetTypeId()) @@ -800,27 +879,47 @@ MailSender::MailSender( Object* sender, MailStationery stationery ) : m_statione break; } } - +/** + * Creates a new MailSender object from an AuctionEntry. + * + * @param sender the AuctionEntry from which this mail is generated. + */ MailSender::MailSender( AuctionEntry* sender ) : m_messageType(MAIL_AUCTION), m_senderId(sender->GetHouseId()), m_stationery(MAIL_STATIONERY_AUCTION) { } - +/** + * Creates a new MailReceiver object. + * + * @param receiver The player receiving the mail. + */ MailReceiver::MailReceiver( Player* receiver ) : m_receiver(receiver), m_receiver_lowguid(receiver->GetGUIDLow()) { } - +/** + * Creates a new MailReceiver object with a specified GUID. + * + * @param receiver The player receiving the mail. + * @param receiver_lowguid The GUID to use instead of the receivers. + */ MailReceiver::MailReceiver( Player* receiver,uint32 receiver_lowguid ) : m_receiver(receiver), m_receiver_lowguid(receiver_lowguid) { ASSERT(!receiver || receiver->GetGUIDLow() == receiver_lowguid); } - +/** + * Adds an item to the MailDraft. + * + * @param item The item to be added to the MailDraft. + * @returns the MailDraft the item was added to. + */ MailDraft& MailDraft::AddItem( Item* item ) { m_items[item->GetGUIDLow()] = item; return *this; } - +/** + * Prepares the items in a MailDraft. + */ void MailDraft::prepareItems(Player* receiver) { if (!m_mailTemplateId || !m_mailTemplateItemsNeed) @@ -846,8 +945,12 @@ void MailDraft::prepareItems(Player* receiver) } } } - -void MailDraft::deleteIncludedItems( bool inDB /*= false*/ ) +/** + * Deletes the items included in a MailDraft. + * + * @param inDB A boolean specifying whether the change should be saved to the database or not. + */ +void MailDraft::deleteIncludedItems( bool inDB /**= false*/ ) { for(MailItemMap::iterator mailItemIter = m_items.begin(); mailItemIter != m_items.end(); ++mailItemIter) { @@ -861,7 +964,12 @@ void MailDraft::deleteIncludedItems( bool inDB /*= false*/ ) m_items.clear(); } - +/* + * Returns a mail to its sender. + * @param sender_acc The id of the account of the sender. + * @param sender_guid The low part of the GUID of the sender. + * @param receiver_guid The low part of the GUID of the reciever. + */ void MailDraft::SendReturnToSender(uint32 sender_acc, uint32 sender_guid, uint32 receiver_guid ) { Player *receiver = sObjectMgr.GetPlayer(MAKE_NEW_GUID(receiver_guid, 0, HIGHGUID_PLAYER)); @@ -902,7 +1010,14 @@ void MailDraft::SendReturnToSender(uint32 sender_acc, uint32 sender_guid, uint32 // will delete item or place to receiver mail list SendMailTo(MailReceiver(receiver,receiver_guid), MailSender(MAIL_NORMAL, sender_guid), MAIL_CHECK_MASK_RETURNED, deliver_delay); } - +/** + * Sends a mail. + * + * @param receiver The MailReceiver to which this mail is sent. + * @param sender The MailSender from which this mail is originated. + * @param checked The mask used to specify the mail. + * @param deliver_delay The delay after which the mail is delivered in seconds + */ void MailDraft::SendMailTo(MailReceiver const& receiver, MailSender const& sender, MailCheckMask checked, uint32 deliver_delay) { Player* pReceiver = receiver.GetPlayer(); // can be NULL @@ -983,3 +1098,4 @@ void MailDraft::SendMailTo(MailReceiver const& receiver, MailSender const& sende else if (!m_items.empty()) deleteIncludedItems(); } +/*! @} */ diff --git a/src/game/Mail.h b/src/game/Mail.h index 392272303..df45eddc4 100644 --- a/src/game/Mail.h +++ b/src/game/Mail.h @@ -15,6 +15,20 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ + +/** + * @addtogroup mailing The mail system + * The mailing system in MaNGOS consists of mostly two files: + * - Mail.h + * - Mail.cpp + * + * @{ + * + * @file Mail.h + * This file contains the the headers needed for MaNGOS to handle mails. + * + */ + #ifndef MANGOS_MAIL_H #define MANGOS_MAIL_H @@ -26,28 +40,37 @@ class Item; class Object; class Player; -#define MAIL_BODY_ITEM_TEMPLATE 8383 // - plain letter, A Dusty Unsent Letter: 889 +#define MAIL_BODY_ITEM_TEMPLATE 8383 ///< - plain letter, A Dusty Unsent Letter: 889 +/// The maximal amount of items a mail can contain. #define MAX_MAIL_ITEMS 12 - +/** + * The type of the mail. + * A mail can have 5 Different Types. + */ enum MailMessageType { MAIL_NORMAL = 0, MAIL_AUCTION = 2, - MAIL_CREATURE = 3, // client send CMSG_CREATURE_QUERY on this mailmessagetype - MAIL_GAMEOBJECT = 4, // client send CMSG_GAMEOBJECT_QUERY on this mailmessagetype - MAIL_ITEM = 5, // client send CMSG_ITEM_QUERY on this mailmessagetype + MAIL_CREATURE = 3, /// client send CMSG_CREATURE_QUERY on this mailmessagetype + MAIL_GAMEOBJECT = 4, /// client send CMSG_GAMEOBJECT_QUERY on this mailmessagetype + MAIL_ITEM = 5, /// client send CMSG_ITEM_QUERY on this mailmessagetype }; - +/** + * A Mask representing the status of the mail. + */ enum MailCheckMask { MAIL_CHECK_MASK_NONE = 0x00, - MAIL_CHECK_MASK_READ = 0x01, - MAIL_CHECK_MASK_AUCTION = 0x04, - MAIL_CHECK_MASK_COD_PAYMENT = 0x08, - MAIL_CHECK_MASK_RETURNED = 0x10 + MAIL_CHECK_MASK_READ = 0x01, /// This mail was read. + MAIL_CHECK_MASK_AUCTION = 0x04, /// This mail was from an auction. + MAIL_CHECK_MASK_COD_PAYMENT = 0x08, /// This mail is payable on delivery. + MAIL_CHECK_MASK_RETURNED = 0x10 /// This mail has been returned. }; -// gathered from Stationery.dbc +/** + * The different types of Stationaries that exist for mails. + * They have been gathered from Stationery.dbc + */ enum MailStationery { MAIL_STATIONERY_UNKNOWN = 1, @@ -58,14 +81,18 @@ enum MailStationery MAIL_STATIONERY_CHR = 65, MAIL_STATIONERY_ORP = 67, // new in 3.2.2 }; - +/** + * Representation of the State of a mail. + */ enum MailState { MAIL_STATE_UNCHANGED = 1, MAIL_STATE_CHANGED = 2, MAIL_STATE_DELETED = 3 }; - +/** + * Answers contained in mails from auctionhouses. + */ enum MailAuctionAnswers { AUCTION_OUTBIDDED = 0, @@ -76,10 +103,21 @@ enum MailAuctionAnswers AUCTION_CANCELED = 5, AUCTION_SALE_PENDING = 6 }; - +/** + * A class to represent the sender of a mail. + */ class MailSender { public: // Constructors + /** + * Creates a new MailSender object. + * + * @param messageType the type of the mail. + * @param sender_guidlow_or_entry The lower part of the GUID of the player sending + * this mail, or the Entry of the non-player object. + * @param stationery The stationary associated with this MailSender. + * + */ MailSender(MailMessageType messageType, uint32 sender_guidlow_or_entry, MailStationery stationery = MAIL_STATIONERY_NORMAL) : m_messageType(messageType), m_senderId(sender_guidlow_or_entry), m_stationery(stationery) { @@ -87,15 +125,20 @@ class MailSender MailSender(Object* sender, MailStationery stationery = MAIL_STATIONERY_NORMAL); MailSender(AuctionEntry* sender); public: // Accessors + /// The Messagetype of this MailSender. MailMessageType GetMailMessageType() const { return m_messageType; } + /// The GUID of the player represented by this MailSender, or the Entry of the non-player object. uint32 GetSenderId() const { return m_senderId; } + /// The stationary associated with this MailSender MailStationery GetStationery() const { return m_stationery; } private: MailMessageType m_messageType; uint32 m_senderId; // player low guid or other object entry MailStationery m_stationery; }; - +/** + * A class to represent the receiver of a mail. + */ class MailReceiver { public: // Constructors @@ -103,76 +146,158 @@ class MailReceiver MailReceiver(Player* receiver); MailReceiver(Player* receiver,uint32 receiver_lowguid); public: // Accessors + /** + * Gets the player associated with this MailReciever + * + * @see Player + * + * @returns a pointer to the Player this mail is for. + * + */ Player* GetPlayer() const { return m_receiver; } + /** + * Gets the low part of the recievers GUID. + * + * @returns the low part of the GUID of the player associated with this MailReciever + */ uint32 GetPlayerGUIDLow() const { return m_receiver_lowguid; } private: Player* m_receiver; uint32 m_receiver_lowguid; }; - +/** + * The class to represent the draft of a mail. + */ class MailDraft { - typedef std::map MailItemMap; + /** + * Holds a Map of GUIDs of items and pointers to the items. + */ + typedef std::map MailItemMap; public: // Constructors + /** + * Creates a new MailDraft object. + * + * @param mailTemplateId The ID of the Template to be used. + * @param a boolean specifying whether the mail needs items or not. + * + */ explicit MailDraft(uint16 mailTemplateId, bool need_items = true) : m_mailTemplateId(mailTemplateId), m_mailTemplateItemsNeed(need_items), m_bodyId(0), m_money(0), m_COD(0) {} + /** + * Creates a new MailDraft object. + * + * @param subject The subject of the mail. + * @param itemTextId The id of the body of the mail. + */ MailDraft(std::string subject, uint32 itemTextId = 0) : m_mailTemplateId(0), m_mailTemplateItemsNeed(false), m_subject(subject), m_bodyId(itemTextId), m_money(0), m_COD(0) {} public: // Accessors + /// Returns the template ID used for this MailDraft. uint16 GetMailTemplateId() const { return m_mailTemplateId; } + /// Returns the subject of this MailDraft. std::string const& GetSubject() const { return m_subject; } + /// Returns the ID of the text of this MailDraft. uint32 GetBodyId() const { return m_bodyId; } + /// Returns the ammount of money in this MailDraft. uint32 GetMoney() const { return m_money; } + /// Returns the Cost of delivery of this MailDraft. uint32 GetCOD() const { return m_COD; } public: // modifiers MailDraft& AddItem(Item* item); + /** + * Modifies the amount of money in a MailDraft. + * + * @param money The amount of money included in this MailDraft. + */ MailDraft& AddMoney(uint32 money) { m_money = money; return *this; } + /** + * Modifies the cost of delivery of the MailDraft. + * + * @param COD the amount to which the cod should be set. + */ MailDraft& AddCOD(uint32 COD) { m_COD = COD; return *this; } public: // finishers void SendReturnToSender(uint32 sender_acc, uint32 sender_guid, uint32 receiver_guid); void SendMailTo(MailReceiver const& receiver, MailSender const& sender, MailCheckMask checked = MAIL_CHECK_MASK_NONE, uint32 deliver_delay = 0); private: void deleteIncludedItems(bool inDB = false); - void prepareItems(Player* receiver); // called from SendMailTo for generate mailTemplateBase items + void prepareItems(Player* receiver); ///< called from SendMailTo for generate mailTemplateBase items + /// The ID of the template associated with this MailDraft. uint16 m_mailTemplateId; + /// Boolean specifying whether items are required or not. bool m_mailTemplateItemsNeed; + /// The subject of the MailDraft. std::string m_subject; + /// The ID of the body of the MailDraft. uint32 m_bodyId; + /// A map of items in this MailDraft. + MailItemMap m_items; ///< Keep the items in a map to avoid duplicate guids (which can happen), store only low part of guid - MailItemMap m_items; // Keep the items in a map to avoid duplicate guids (which can happen), store only low part of guid - + /// The amount of money in this MailDraft. uint32 m_money; + /// The cod amount of this MailDraft. uint32 m_COD; }; - +/** + * Structure holding information about an item in the mail. + */ struct MailItemInfo { - uint32 item_guid; - uint32 item_template; + uint32 item_guid; ///< the GUID of the item. + uint32 item_template; ///< the ID of the template of the item. }; - +/** + * Structure that holds an actual mail. + */ struct Mail { - uint32 messageID; + /// the ID of the message contained in the mail. + uint32 messageID; + /// the type of the message uint8 messageType; + /// the stationary used in this mail. uint8 stationery; + /// the ID of the template this mail is based on. uint16 mailTemplateId; + /// the GUID of the player that sent this mail. uint32 sender; + /// the GUID of the player that this mail is sent to. uint32 receiver; + /// the subject of the mail std::string subject; + /// The ID of the itemtext. uint32 itemTextId; + /// A vector containing Information about the items in this mail. std::vector items; + /// A vector containing Information about the items that where already take from this mail. std::vector removedItems; + /// The time at which this mail will expire time_t expire_time; + /// The time at which this mail (was/will be) delivered time_t deliver_time; + /// The amount of money contained in this mail. uint32 money; + /// The amount of money the receiver has to pay to get this mail. uint32 COD; + /// The time at which this mail was read. uint32 checked; + /// The state of this mail. MailState state; + /** + * Adds an item to the mail. + * This method adds an item to mail represented by this structure. + * There is no checking done whether this is a legal action or not; it is up + * to the caller to make sure there is still room for more items in the mail. + * + * @param itemGuidLow the GUID(low) of the item added to the mail. + * @param item_template the ID of the template of the item. + * + */ void AddItem(uint32 itemGuidLow, uint32 item_template) { MailItemInfo mii; @@ -181,6 +306,16 @@ struct Mail items.push_back(mii); } + /** + * Removes an item from the mail. + * This method removes an item from the mail. + * + * @see MailItemInfo + * + * @param item_guid The GUID of the item to be removed. + * @returns true if the item was removed, or false if no item with that GUID was found. + * + */ bool RemoveItem(uint32 item_guid) { for(std::vector::iterator itr = items.begin(); itr != items.end(); ++itr) @@ -194,7 +329,15 @@ struct Mail return false; } + /* + * Checks whether a mail contains items or not. + * HasItems() checks wether the mail contains items or not. + * + * @returns true if the mail contains items, false otherwise. + * + */ bool HasItems() const { return !items.empty(); } }; #endif +/*! @} */ diff --git a/src/shared/revision_nr.h b/src/shared/revision_nr.h index a2dba2bf1..ab919e33b 100644 --- a/src/shared/revision_nr.h +++ b/src/shared/revision_nr.h @@ -1,4 +1,4 @@ #ifndef __REVISION_NR_H__ #define __REVISION_NR_H__ - #define REVISION_NR "9405" + #define REVISION_NR "9406" #endif // __REVISION_NR_H__