yate学习--yatesip.h--class YSIP_API SIPMessage : public RefObject

请声明出处：http://blog.csdn.net/u012377333/article/details/45917579

本文开始详细的学习yate里面自定义的SIP协议库，消息体的定义：

/**
 * An object that holds the sip message parsed into this library model.
 * 一个保存被解析的sip信息到这个库模型的对象
 * This class can be used to parse a sip message from a text buffer, or it
 * can be used to create a text buffer from a sip message.
 * 这个类可以被用于从text的缓冲下中解析一个sip消息，
 * 或者能被用于从sip消息创建一个text缓冲区
 * @short A container and parser for SIP messages
 */
class YSIP_API SIPMessage : public RefObject
{
public:
    /**
     * Various message flags
	 * 多种消息标志
     */
    enum Flags {
	Defaults          =      0,
	NotReqRport       = 0x0001,
	NotAddAllow       = 0x0002,
	NotAddAgent       = 0x0004,
	RportAfterBranch  = 0x0008,
	NotSetRport       = 0x0010,
	NotSetReceived    = 0x0020,
	NoConnReuse       = 0x0040,      // Don't add 'alias' parameter to Via header (reliable only)
    };

    /**
     * Copy constructor
	 * 拷贝构造函数
     */
    SIPMessage(const SIPMessage& original);

    /**
     * Creates a new, empty, outgoing SIPMessage.
	 * 创建一个新的，空的，外出的sip消息
     */
    SIPMessage(const char* _method, const char* _uri, const char* _version = "SIP/2.0");

    /**
     * Creates a new SIPMessage from parsing a text buffer.
	 * 创建一个的新的sip消息从解析text缓冲区
     * @param ep Party to set in message
	 * @参数ep，设置到消息的party
     * @param buf Buffer to parse
	 * @参数buf，要解析的缓冲区
     * @param len Optional buffer length
	 * @参数len， 可选择的缓冲区的大小
     * @param bodyLen Pointer to body length to be set if the message was received
     *  on a stream transport. If not 0 the buffer must contain the message
     *  without its body
	 * @参数bodylen， 指向去设置在流传输中被接受的消息的长度的指针，如果不为0,
	 * 缓冲区必须包含不包括消息体的消息
     */
    SIPMessage(SIPParty* ep, const char* buf, int len = -1, unsigned int* bodyLen = 0);

    /**
     * Creates a new SIPMessage as answer to another message.
	 * 创建一个新的sip消息去应答另外一个消息
     */
    SIPMessage(const SIPMessage* message, int _code, const char* _reason = 0);

    /**
     * Creates an ACK message from an original message and a response.
	 * 创建一个确认消息从一个原始的消息并且响应
     */
    SIPMessage(const SIPMessage* original, const SIPMessage* answer);

    /**
     * Destroy the message and all
	 * 销毁消息
     */
    virtual ~SIPMessage();

    /**
     * Construct a new SIP message by parsing a text buffer
	 * 通过解析一个text缓冲区来构造一个新的sip消息
     * @param ep Party to set in message
	 * @参数ep，设置到消息的party
     * @param buf Buffer to parse
	 * @参数buf，要解析的缓冲区
     * @param len Optional buffer length
	 * @参数len， 可选择的缓冲区的大小
     * @param bodyLen Pointer to body length to be set if the message was received
     *  on a stream transport. If not 0 the buffer must contain the message
     *  without its body
	 * @参数bodylen， 指向去设置在流传输中被接受的消息的长度的指针，如果不为0,
	 * 缓冲区必须包含不包括消息体的消息
     * @return A pointer to a valid new message or NULL
	 * @返回指向有效的新消息的指针或者NULL
     */
    static SIPMessage* fromParsing(SIPParty* ep, const char* buf, int len = -1,
	unsigned int* bodyLen = 0);

    /**
     * Build message's body. Reset it before.
	 * 构建消息体，之前重置
     * This method should be called after parsing a partial message (headers only)
	 * 这个方法必须在解析部分消息（仅仅是消息头）之后调用
     * @param buf Buffer to parse
	 * @参数buf，要解析的缓冲区
     * @param len Optional buffer length
	 * @参数len， 可选择的缓冲区的大小
     */
    void buildBody(const char* buf, int len = -1);

    /**
     * Complete missing fields with defaults taken from a SIP engine
	 * 从sip engine中完成丢失字段的默认值
     * @param engine Pointer to the SIP engine to use for extra parameters
	 * @参数engine，要使用附加参数的sip engine的指针
     * @param user Username to set in the From header instead of that in rURI
	 * @参数user，设置到文件头的From的用户名代替rURI
     * @param domain Domain to use in From instead of the local IP address
	 * @参数domain，用于文件头From代替本地IP地址的域
     * @param dlgTag Value of dialog tag parameter to set in To header
	 * @参数dlgTag，设置到消息头的会话标志参数
     * @param flags Miscellaneous completion flags, -1 to take them from engine
	 * @参数标志,杂项完成的标志,-1从engine中使用
     */
    void complete(SIPEngine* engine, const char* user = 0, const char* domain = 0, const char* dlgTag = 0, int flags = -1);

    /**
     * Copy an entire header line (including all parameters) from another message
	 * 从另外一个消息拷贝一个全部的消息头列（包含所有的参数）
     * @param message Pointer to the message to copy the header from
	 * @参数message，指向要拷贝文件头的消息的指针
     * @param name Name of the header to copy
	 * @参数name， 要拷贝的消息头的名称
     * @param newName New name to force in headers, NULL to just copy
	 * @参数newName，消息头的新名称,NULL仅仅拷贝
     * @return True if the header was found and copied
	 * @返回true，如果消息头被找到并且被拷贝
     */
    bool copyHeader(const SIPMessage* message, const char* name, const char* newName = 0);

    /**
     * Copy multiple header lines (including all parameters) from another message
	 * 从另外一个消息拷贝一个全部的消息头列（包含所有的参数）
     * @param message Pointer to the message to copy the header from
	 * @参数message，指向要拷贝文件头的消息的指针
     * @param name Name of the headers to copy
	 * @参数name， 要拷贝的消息头的名称
     * @param newName New name to force in headers, NULL to just copy
	 * @参数newName，消息头的新名称,NULL仅仅拷贝
     * @return Number of headers found and copied
	 * @返回消息头被找到并且被拷贝的数量
     */
    int copyAllHeaders(const SIPMessage* message, const char* name, const char* newName = 0);

    /**
     * Get the endpoint this message uses
	 * 获得这个消息的 sip party
     * @return Pointer to the endpoint of this message
	 * @返回指向消息的 sip party的指针
     */
    inline SIPParty* getParty() const
	{ return m_ep; }

    /**
     * Set the endpoint this message uses
	 * 设置这个消息的 sip party
     * @param ep Pointer to the endpoint of this message
	 * @参数ep,指向消息的 sip party的指针
     */
    void setParty(SIPParty* ep = 0);

    /**
     * Check if this message is valid as result of the parsing
	 * 核查这个消息解析的结果是否是有效的
     */
    inline bool isValid() const
	{ return m_valid; }

    /**
     * Check if this message is an answer or a request
	 * 核查消息是一个应答还是一个请求
     */
    inline bool isAnswer() const
	{ return m_answer; }

    /**
     * Check if this message is an outgoing message
	 * 核查该消息是否是一个外出的消息
     * @return True if this message should be sent to remote
	 * @返回true，如果该消息被发送到远端
     */
    inline bool isOutgoing() const
	{ return m_outgoing; }

    /**
     * Check if this message is an ACK message
	 * 检查这个消息是否是一个确认消息
     * @return True if this message has an ACK method
	 * @返回rtue 如果这个消息是一个确认的方式
     */
    inline bool isACK() const
	{ return m_ack; }

    /**
     * Check if this message is handled by a reliable protocol
	 * 核查该消息是否被可靠的协议处理
     * @return True if a reliable protocol (TCP, SCTP) is used
	 * @返回true，如果使用可靠的协议（tcp,sctp）
     */
    inline bool isReliable() const
	{ return m_ep ? m_ep->isReliable() : false; }

    /**
     * Get the Command Sequence number from this message
	 * 从该消息中获得信令的序号
     * @return Number part of CSEQ in this message
	 * @返回消息的CSEQ部分的序号
     */
    inline int getCSeq() const
	{ return m_cseq; }

    /**
     * Get the last flags used by this message
	 * 获得被该消息使用的最后一个标志
     * @return Flags last used, ORed together
	 * @返回最后一个被使用的标志
     */
    inline int getFlags() const
	{ return m_flags; }

    /**
     * Find a header line by name
	 * 通过名称找到消息头的列
     * @param name Name of the header to locate
	 * @参数name，定位消息头的名称
     * @return A pointer to the first matching header line or 0 if not found
	 * @返回指向第一个匹配到的消息头列的指针，或者为0 如果没有找到
     */
    const MimeHeaderLine* getHeader(const char* name) const;

    /**
     * Find the last header line that matches a given name name
	 * 找到最后匹配消息头列的名称
     * @param name Name of the header to locate
	 * @参数name，定位消息头的名称
     * @return A pointer to the last matching header line or 0 if not found
	 * @返回指向最后一个匹配到的消息头列的指针，或者为0 如果没有找到
     */
    const MimeHeaderLine* getLastHeader(const char* name) const;

    /**
     * Count the header lines matching a specific name
	 * 计算匹配特殊名称的消息头列的条数
     * @param name Name of the header to locate
	 * @参数name，定位消息头的名称
     * @return Number of matching header lines
	 * @返回匹配消息头列的数量
     */
    int countHeaders(const char* name) const;

    /**
     * Find a header parameter by name
	 * 通过名称找到消息的参数
     * @param name Name of the header to locate
	 * @参数name，定位消息头的名称
     * @param param Name of the parameter to locate in the tag
	 * @参数param，要定位的参数的名称
     * @param last Find the last header with that name instead of first
	 * @参数last,找到名称最后的消息头代替第一个
     * @return A pointer to the first matching header line or 0 if not found
	 * @返回指向第一个匹配到的消息头列的指针，或者为0 如果没有找到
     */
    const NamedString* getParam(const char* name, const char* param, bool last = false) const;

    /**
     * Get a string value (without parameters) from a header line
	 * 从消息头列中获取字符串值(没有参数)
     * @param name Name of the header to locate
	 * @参数name，定位消息头的名称
     * @param last Find the last header with that name instead of first
	 * @参数last,找到名称最后的消息头代替第一个
     * @return The value hold in the header or an empty String
	 * @返回保存消息头的值，或者空串
     */
    const String& getHeaderValue(const char* name, bool last = false) const;

    /**
     * Get a string value from a parameter in a header line
	 * 从消息头列中获取参数的字符串值
     * @param name Name of the header to locate
	 * @参数name，定位消息头的名称
     * @param param Name of the parameter to locate in the tag
	 * @参数param，要定位的参数的名称
     * @param last Find the last header with that name instead of first
	 * @参数last,找到名称最后的消息头代替第一个
     * @return The value hold in the parameter or an empty String
	 * @返回保存消息头参数的值，或者空串
     */
    const String& getParamValue(const char* name, const char* param, bool last = false) const;

    /**
     * Append a new header line constructed from name and content
	 * 添加一个新的被构造的消息头从名称和内容
     * @param name Name of the header to add
	 * @参数name，要添加到消息头的名称
     * @param value Content of the new header line
	 * @参数value，新消息头的内容
     */
    inline void addHeader(const char* name, const char* value = 0)
	{ header.append(new MimeHeaderLine(name,value)); }

    /**
     * Append an already constructed header line
	 * 添加一个已近被构造好的消息头列
     * @param line Header line to add
	 * @参数line，要添加的消息头列
     */
    inline void addHeader(MimeHeaderLine* line)
	{ header.append(line); }

    /**
     * Clear all header lines that match a name
	 * 清理所有匹配名称的消息头列
     * @param name Name of the header to clear
	 * @参数name，要清理的名称
     */
    void clearHeaders(const char* name);

    /**
     * Set a header line constructed from name and content
	 * 从名称和内容来设置一个被构造好的消息头列
     */
    inline void setHeader(const char* name, const char* value = 0)
	{ clearHeaders(name); addHeader(name,value); }

    /**
     * Construct a new authorization line based on credentials and challenge
	 * 构造一个新的鉴权列基于证书和挑战（？）
     * @param username User account name
	 * @参数username，账户的用户名
     * @param password Clear text password for the account
	 * @参数password,账户的明文密码
     * @param meth Method to include in the authorization digest
	 * @参数meth，鉴权摘要的方法
     * @param uri URI to include in the authorization digest
	 * @参数uri，鉴权摘要的地址
     * @param proxy Set to true to authenticate to a proxy, false to a server
	 * @参数proxy,设置为true，代理鉴权，false，服务器鉴权
     * @param engine Optional engine processing this message
	 * @参数engine，可选的引擎处理此消息
     * @return A new authorization line to be used in a new transaction
	 * @返回一个新的鉴权列被用于新的会话
     */
    MimeAuthLine* buildAuth(const String& username, const String& password,
	const String& meth, const String& uri, bool proxy = false, SIPEngine* engine = 0) const;

    /**
     * Construct a new authorization line based on this answer and original message
	 * 构造一个新的鉴权列基于应答和原始的消息
     * @param original Origianl outgoing message
	 * @参数original，原始的外出消息
     * @param engine Optional engine processing this message
	 * @参数engine，可选的引擎处理此消息
     * @return A new authorization line to be used in a new transaction
	 * @返回一个新的鉴权列被用于新的会话
     */
    MimeAuthLine* buildAuth(const SIPMessage& original, SIPEngine* engine = 0) const;

    /**
     * Prepare the message for automatic client transaction authentication.
	 * 为自动的客户端鉴权会话准备用户名和密码
     * @param username Username for auto authentication
	 * @参数username，鉴权的用户名
     * @param password Password for auto authentication
	 * @参数password，鉴权的密码
     */
    inline void setAutoAuth(const char* username = 0, const char* password = 0)
	{ m_authUser = username; m_authPass = password; }

    /**
     * Retrieve the username to be used for auto authentication
	 * 检索被用于鉴权的用户名
     * @return Username for auto authentication
     */
    inline const String& getAuthUsername() const
	{ return m_authUser; }

    /**
     * Retrieve the password to be used for auto authentication
	 * 检索被用于鉴权的密码
     * @return Password for auto authentication
     */
    inline const String& getAuthPassword() const
	{ return m_authPass; }

    /**
     * Extract routes from Record-Route: headers
	 * 从记录路由中提取路线:头
     * @return A list of MimeHeaderLine representing SIP routes
	 * @返回标示sip路由的MimeHeaderLine链表
     */
    ObjList* getRoutes() const;

    /**
     * Add Route: headers to an outgoing message
	 * 添加路由:外出消息头
     * @param routes List of MimeHeaderLine representing SIP routes
	 * @返回标示sip路由的MimeHeaderLine链表
     */
    void addRoutes(const ObjList* routes);

    /**
     * Creates a binary buffer from a SIPMessage.
	 * 从sip消息中创建一个2进制的缓冲区
     */
    const DataBlock& getBuffer() const;

    /**
     * Creates a text buffer from the headers.
	 * 从文件头创建一个文本缓冲区
     */
    const String& getHeaders() const;

    /**
     * Set a new body for this message
	 * 设置新的消息体
     */
    void setBody(MimeBody* newbody = 0);

    /**
     * Sip Version
	 * sip 版本
     */
    String version;

    /**
     * This holds the method name of the message.
	 * 这个消息的方法名称
     */
    String method;

    /**
     * URI of the request
	 * 请求的地址
     */
    String uri;

    /**
     * Status code
	 * 状态码
     */
    int code;

    /**
     * Reason Phrase
	 * 原因描述
     */
    String reason;

    /**
     * All the headers should be in this list.
	 * 消息头
     */
    ObjList header;

    /**
     * All the body related things should be here, including the entire body and
     * the parsed body.
	 * 消息体
     */
    MimeBody* body;

protected:
    bool parse(const char* buf, int len, unsigned int* bodyLen);
    bool parseFirst(String& line);
    SIPParty* m_ep;
    bool m_valid;
    bool m_answer;
    bool m_outgoing;
    bool m_ack;
    int m_cseq;
    int m_flags;
    mutable String m_string;
    mutable DataBlock m_data;
    String m_authUser;
    String m_authPass;
private:
    SIPMessage(); // no, thanks
};