【Live555】live555源码详解（七）：GenericMediaServer、RTSPServer、RTSPClient

【Live555】live555源码详解系列笔记

继承协作关系图

下面红色表示本博客将要介绍的三个类所在的位置：
GenericMediaServer、RTSPServer、RTSPClient

14、GenericMediaServer

GenericMediaServer 继承自 Medium，依赖关系图如下：

使用 GenericMediaServer 的关系图：

GenericMediaServer 的协作图

GenericMediaServer 的继承关系

主要接口：

	/ServerMediaSession 相关接口：增、查、删、关闭
	/添加 服务媒体会话 ServerMediaSession
	void addServerMediaSession(ServerMediaSession* serverMediaSession);

	/查找 服务媒体会话 ServerMediaSession
	virtual ServerMediaSession* lookupServerMediaSession(char const* streamName, Boolean isFirstLookupInSession = True);

	/删除 从我们的查询表中删除“ServerMediaSession”对象，因此它将不再被新客户机访问。
	/然而，任何使用这个“ServerMediaSession”对象的*现有的*客户机会话将继续流。在所有这些客户端会话关闭之前，“ServerMediaSession”对象不会被删除。
	/要删除“ServerMediaSession”对象，并关闭使用它的所有客户端会话，请调用“deleteServerMediaSession(ServerMediaSession)”。
	void removeServerMediaSession(ServerMediaSession* serverMediaSession);
	virtual void removeServerMediaSession(char const* streamName);

	/关闭 (从服务器上)当前正在使用这个“ServerMediaSession”对象的所有客户机会话。
	/但是请注意，新客户机仍然可以访问“ServerMediaSession”对象。
	void closeAllClientSessionsForServerMediaSession(ServerMediaSession* serverMediaSession);
	virtual void closeAllClientSessionsForServerMediaSession(char const* streamName);
	
	/关闭后删除，等于 closeAllClientSessionsForServerMediaSession + removeServerMediaSession
	void deleteServerMediaSession(ServerMediaSession* serverMediaSession);
	virtual void deleteServerMediaSession(char const* streamName);
	
	/客户会话数
	unsigned numClientSessions() const { return fClientSessions->numEntries(); 

15、RTSPServer

RTSPServer 继承自 GenericMediaServer，依赖关系图如下：

使用 RTSPServer 的关系图：

RTSPServer 协作图

RTSPServer 继承关系图

主要接口：

	/静态函数，创建RTSPServer，参数说明：
	/	ourPort：如果 ourPort 为 0，程序选择端口号
	/	authDatabase：调用方负责回收authDatabase
	/	reclamationSeconds：回收时间，如果在至少“reclamationSeconds”秒内没有收到来自客户端的RTSP命令或RTCP“RR”包，
	/ 		那么每个客户端的“RTSPClientSession”状态将被回收(相应的RTP流被销毁)。
	static RTSPServer* createNew(UsageEnvironment& env, Port ourPort = 554,
			       UserAuthenticationDatabase* authDatabase = NULL,
			       unsigned reclamationSeconds = 65);

	/ 静态函数，由名字获取RTSPServer
	static Boolean lookupByName(UsageEnvironment& env, char const* name,
			      RTSPServer*& resultServer);
	
	/ 使用 registerStream 前，需要实现处理注册相应的接口：responseHandlerForREGISTER
	typedef void (responseHandlerForREGISTER)(RTSPServer* rtspServer, unsigned requestId, int resultCode, char* resultString);
	
	/ RTSP "REGISTER"命令：向给定的远程客户端(通过名称和端口号指定)“注册”由“serverMediaSession”表示的流。
	/ 该函数返回一个唯一的数字，可以用来识别请求;这个数字也被传递给“responseHandler”。
	unsigned registerStream(ServerMediaSession* serverMediaSession,
			  char const* remoteClientNameOrAddress, portNumBits remoteClientPortNum,
			  responseHandlerForREGISTER* responseHandler,
			  char const* username = NULL, char const* password = NULL,
			  Boolean receiveOurStreamViaTCP = False,
			  char const* proxyURLSuffix = NULL);
	
	/ 使用 deregisterStream 前，需要实现处理注销流的接口：responseHandlerForDEREGISTER
	typedef void (responseHandlerForDEREGISTER)(RTSPServer* rtspServer, unsigned requestId, int resultCode, char* resultString);
	
	/ RTSP "DEREGISTER"命令：用于关闭以前的“registerStream()”
	unsigned deregisterStream(ServerMediaSession* serverMediaSession,
			    char const* remoteClientNameOrAddress, portNumBits remoteClientPortNum,
			    responseHandlerForDEREGISTER* responseHandler,
			    char const* username = NULL, char const* password = NULL,
			    char const* proxyURLSuffix = NULL);
  
	/ 返回一个"rtsp://" URL，可以用来访问指定的会话(它必须已经被添加到我们使用"addServerMediaSession()")。
	/ 注意：这个字符串是动态分配的;调用者应该删除[]
	char* rtspURL(ServerMediaSession const* serverMediaSession, int clientSocket = -1) const;

	/ 类似于"rtspURL()"，只是它只返回每个会话的"rtsp://" URL所使用的公共前缀。
	/ 注意：这个字符串是动态分配的;调用者应该删除[]
	char* rtspURLPrefix(int clientSocket = -1) const;

	/ 将服务器的身份验证数据库更改为“newDB”，返回一个指向旧数据库的指针(如果有的话)。
	UserAuthenticationDatabase* setAuthenticationDatabase(UserAuthenticationDatabase* newDB);

	/ 禁止使用TCP来传输RTP
	void disableStreamingRTPOverTCP() { fAllowStreamingRTPOverTCP = False; }

	/ (尝试)在指定端口上启用rtsp -over http隧道。
	/ 如果指定的端口可以以这种方式使用(即:，它还没有用于单独的HTTP服务器)。
	Boolean setUpTunnelingOverHTTP(Port httpPort);

	/ 按主机字节顺序排列。(如果不存在，返回0)
	portNumBits httpServerPortNum() const;

16、RTSPClient

RTSPClient 继承自 Medium，依赖关系图如下：

使用 RTSPClient 的关系图：

RTSPClient 协作图

RTSPClient 继承关系图

主要接口：

	/ 如果“tunnelOverHTTPPortNum”非零，我们将RTSP(和RTP)通过一个具有给定端口号的HTTP连接进行隧道（安全加密链路）
	/ 参见使用Apple文档中描述的技术<http://developer.apple.com/documentation/QuickTime/QTSS/Concepts/chapter_2_section_14.html>
	/ 如果"socketNumToServer"是 >= 0，那么它是到服务器的一个已经存在的TCP连接的套接字号码。(在本例中，“rtspURL”必须指向套接字的端点，以便可以通过套接字访问它。)
	static RTSPClient* createNew(UsageEnvironment& env, char const* rtspURL,
			       int verbosityLevel = 0,
			       char const* applicationName = NULL,
			       portNumBits tunnelOverHTTPPortNum = 0,
			       int socketNumToServer = -1);

	/ 回调函数：响应RTSP命令而调用的函数。参数如下:
	/ 	rtspClient：发出原始命令的“RTSPClient”对象。
	/ 	resultCode：如果为零，则命令成功完成。如果非零，则表示命令没有成功完成，“resultCode”表示错误，如下所示:
	/		resultCode为正值代表是一个RTSP错误代码(例如，404表示“未找到”)
	/		resultCode为负值代表是套接字/网络错误;
	/		resultCode为0值时，可以通过“errno”来查询错误。
	/	"resultString":与响应一起返回的('\0'终止的)字符串，否则为NULL。
	/		特别的：
	/			针对“DESCRIBE”命令，如果成功了，“resultString”中是媒体会话的SDP描述。
	/			针对“OPTIONS”命令，如果成功了，“resultString”中是允许的命令列表。
	/		注意，如果resultCode是非零，这个字符串可以表示一个错误消息。
	/		此外，“resultString”可以为空，即使“resultCode”为零(例如，如果RTSP命令成功，但没有包含适当的结果头)
	/		还要注意，这个字符串是动态分配的，处理程序(或调用者)必须使用“delete[]”来释放它。
	typedef void (responseHandler)(RTSPClient* rtspClient, int resultCode, char* resultString);

	/ 发出RTSP “DESCRIBE” 命令，然后返回命令中使用的“CSeq”序列号。参数如下：
	/ 	responseHandler：需要先实现 responseHandler 回调函数，用于处理“DESCRIBE”命令的相应。如果发送时就出现错误，将会直接返回一个错误码。
	/ 	authenticator：(可选的)用于访问控制。如果您有用户名和密码字符串，您可以通过传递一个实际参数来使用它，该参数是您通过创建一个“Authenticator(用户名，密码)对象”创建的。
	/ 注意，如果您提供一个非空的“authenticator”参数，那么您只需要对您发送的第一个命令执行此操作。
	unsigned sendDescribeCommand(responseHandler* responseHandler, Authenticator* authenticator = NULL);

	/ 发送RTSP “OPTIONS” 命令，然后返回命令中使用的“CSeq”序列号。参数参考 sendDescribeCommand
	unsigned sendOptionsCommand(responseHandler* responseHandler, Authenticator* authenticator = NULL);

	/ 发送RTSP “ANNOUNCE” 命令，使用 sdpDescription 作为参数，然后返回命令中使用的“CSeq”序列号。参数参考 sendDescribeCommand
	unsigned sendAnnounceCommand(char const* sdpDescription, responseHandler* responseHandler, Authenticator* authenticator = NULL);

	/ 发送RTSP “SETUP” 命令，然后返回命令中使用的“CSeq”序列号。参数参考 sendDescribeCommand
	unsigned sendSetupCommand(MediaSubsession& subsession, responseHandler* responseHandler,
			    Boolean streamOutgoing = False,
			    Boolean streamUsingTCP = False,
			    Boolean forceMulticastOnUnspecified = False,
			    Authenticator* authenticator = NULL);
	
	/ 在会话session或子会话subsession期间发送RTSP “PLAY” 命令，然后返回命令中使用的“CSeq”序列号。
	/ 注意:start=-1表示重新播放;end=-1表示播放到结束
	unsigned sendPlayCommand(MediaSession& session, responseHandler* responseHandler,
			   double start = 0.0f, double end = -1.0f, float scale = 1.0f,
			   Authenticator* authenticator = NULL);
	unsigned sendPlayCommand(MediaSubsession& subsession, responseHandler* responseHandler,
			   double start = 0.0f, double end = -1.0f, float scale = 1.0f,
			   Authenticator* authenticator = NULL);
	
	/ 同上，用于发送包含“绝对”时间范围的“PLAY”命令: 时间格式为YYYYMMDDTHHMMSSZ
	unsigned sendPlayCommand(MediaSession& session, responseHandler* responseHandler,
			   char const* absStartTime, char const* absEndTime = NULL, float scale = 1.0f,
			   Authenticator* authenticator = NULL);
	unsigned sendPlayCommand(MediaSubsession& subsession, responseHandler* responseHandler,
			   char const* absStartTime, char const* absEndTime = NULL, float scale = 1.0f,
			   Authenticator* authenticator = NULL);

	/ 在会话session或子会话subsession期间发送RTSP “PAUSE” 命令，然后返回命令中使用的“CSeq”序列号。
	unsigned sendPauseCommand(MediaSession& session, responseHandler* responseHandler, Authenticator* authenticator = NULL);
	unsigned sendPauseCommand(MediaSubsession& subsession, responseHandler* responseHandler, Authenticator* authenticator = NULL);

	/ 在会话session或子会话subsession期间发送RTSP “RECORD” 命令，然后返回命令中使用的“CSeq”序列号。
	unsigned sendRecordCommand(MediaSession& session, responseHandler* responseHandler, Authenticator* authenticator = NULL);
	unsigned sendRecordCommand(MediaSubsession& subsession, responseHandler* responseHandler, Authenticator* authenticator = NULL);
	
	/ 在会话session或子会话subsession期间发送RTSP “TEARDOWN” 命令，然后返回命令中使用的“CSeq”序列号。
	unsigned sendTeardownCommand(MediaSession& session, responseHandler* responseHandler, Authenticator* authenticator = NULL);
	unsigned sendTeardownCommand(MediaSubsession& subsession, responseHandler* responseHandler, Authenticator* authenticator = NULL);

	/ 在会话session期间发送RTSP “SET_PARAMETER” 命令，然后返回命令中使用的“CSeq”序列号。
	unsigned sendSetParameterCommand(MediaSession& session, responseHandler* responseHandler,
				   char const* parameterName, char const* parameterValue,
				   Authenticator* authenticator = NULL);

	/ 在会话session期间发送RTSP “GET_PARAMETER” 命令，然后返回命令中使用的“CSeq”序列号。
	unsigned sendGetParameterCommand(MediaSession& session, responseHandler* responseHandler, char const* parameterName,
				   Authenticator* authenticator = NULL);

	/ 发送简短的“dummy假的”（例如，空的RTP或RTCP）UDP数据包到服务器。如果我们在NAT后面，为了增加RTP/RTCP数据包从服务器到达我们的可能性。
	/ 官方会在发送每个“PLAY”命令之前自动完成这个操作：官方提示：除非您知道自己在做什么，否则您不应该自己调用这些函数。
	void sendDummyUDPPackets(MediaSession& session, unsigned numDummyPackets = 2);
	void sendDummyUDPPackets(MediaSubsession& subsession, unsigned numDummyPackets = 2);
	
	/ 使用“PLAY”命令中的“Speed:”选项，将(录制的)媒体下载速度设置为给定值，支持更快的下载速度。
	void setSpeed(MediaSession& session, float speed = 1.0f);

	/ 更改之前执行的命令的响应处理程序(其操作返回“cseq”)。
	/ 要关闭该命令的任何响应处理，请使用“newResponseHandler”值为NULL。例如，这可以作为命令上的“超时处理程序”实现的一部分。
	/ 如果“cseq”是之前执行的有效命令(其响应仍未处理)，则该函数返回True。
	Boolean changeResponseHandler(unsigned cseq, responseHandler* newResponseHandler);

	/ 返回socket描述符
	int socketNum() const { return fInputSocketNum; }

	/ 静态函数，由名字返回对应的 RTSPClient
	static Boolean lookupByName(UsageEnvironment& env, char const* sourceName, RTSPClient*& resultClient);

	/ 解析“url”，"rtsp://[[:]@][:][/]"
	/ 请注意，返回的“用户名”和“密码”要么为空，要么为堆分配的字符串，调用者随后必须删除这些字符串[]。
	Boolean parseRTSPURL(char const* url, char*& username, char*& password, NetAddress& address, portNumBits& portNum, char const** urlSuffix = NULL);
	
	/ 设置RTSP“User-Agent:”头文件中使用的替代字符串
	void setUserAgentString(char const* userAgentName);
	
	/ 如果不希望服务器请求“Basic”身份验证，请调用此函数，(这将导致客户端通过网络发送用户名和密码)。
	void disallowBasicAuthentication() { fAllowBasicAuthentication = False; }

	/ 返回会话超时参数
	unsigned sessionTimeoutParameter() const { return fSessionTimeoutParameter; }

	/ 返回URL
	char const* url() const { return fBaseURL; }

	/ 使用TLS
	void useTLS() { fTLS.isNeeded = True; }

【Live555】live555源码详解系列笔记