mangos-mirror/server
0
0
Fork 0
mirror of https://github.com/mangosfour/server.git synced 2025-12-15 19:37:02 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

[9406] Documentation mail system.

Browse source 
Signed-off-by: AlexDereka <dereka.alex@gmail.com>
This commit is contained in:
Gotisch 2010-02-18 06:40:22 +03:00 • committed by AlexDereka
parent 5af05a314e
commit 34c51c7bf6
3 changed files with 310 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

166
src/game/Mail.cpp
View file

@ -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();
}
/*! @} */

193
src/game/Mail.h
View file

@ -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<uint32, Item*> MailItemMap;
/**
* Holds a Map of GUIDs of items and pointers to the items.
*/
typedef std::map<uint32, Item*> 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<MailItemInfo> items;
/// A vector containing Information about the items that where already take from this mail.
std::vector<uint32> 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<MailItemInfo>::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
/*! @} */

2
src/shared/revision_nr.h
View file

@ -1,4 +1,4 @@
#ifndef __REVISION_NR_H__
#define __REVISION_NR_H__
#define REVISION_NR "9405"
#define REVISION_NR "9406"
#endif // __REVISION_NR_H__