封装了P2P连接与数据传送过程的DLL正式版-PPQ.DLL v1.0（二）

王朝vc·作者佚名 2006-01-08

宽屏版字体: 小|中|大|超大

十 PPQ.DLL的消息

* 对除特别声明外的所有消息都适应的规范

* 当接收到一个以PTask对象的指针作为lParam参数的消息时，你可以决定是否要继续使用该对象。

* 如果想继续使用该对象，则先调用InitValue()方法，InitValue()不会改变原有的赋值。

* 如果你想继续工作，则不用改动已经赋过值的属性，而直接调用StartTask()方法。

* 如果你想完成其它的工作，你必需要设定相应的属性的值，就象你新创建了一个该PTask对象一样，然后再调用StartTask()方法。

* 如果不想继续使用该对象，你需要delete这个对象。如果你在delete这个对象这前，不希望删除PRECVINFO结构，你可以保存该指向该结构的指针，然后设定m_lprRecvInfo=NULL。

* PTask对象中的m_dwIdentify属性保存的是DLL外部在创建PTask对象时为PTask对象设定的标识，通过该标识应该可以正确地得到一个仍然有效的PTask对象。也就是说，当接到该标识的参数时，该标识所表示的PTask对象不一定还是有效的，这个PTask对象可能已经被delete啦，你必需通过检测，以确保PTask对象是有效的，才能正确地引用这个对象，否则应该丢弃刚收到的这个消息。这点一定要注意。

* * * * * * * * * * * * *

*消息名称： OMSG_ALL_CONNECT_END

*类型：必需响应的消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* LPARAM lParam -指向PTask对象的指针

*说明：

* 表明一个PTask对象的所有的连接请求都已终止，但是线程组中的线程并未终止。

接到该指令时不能delete这个PTask对象。

* * * * * * * * * * * * *

*消息名称： OMSG_CREATE_NEW_OBJ

*类型：必需响应的消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*说明：

在消息函数执行体中直接调用PDefine::SCreateNewObj()静态方法，

传递wParam和lParam参数。其它不必作任何事情。

* * * * * * * * * * * * *

*消息名称： OMSG_CREATE_NEW_THREAD

*类型：必需响应的消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* LPARAM lParam -指向PTask对象的指针

*说明：

* 你可以通过判断PTask->m_dwIdentify==0来得知该PTask对象是否已设定了标识。

如果值为0，你需要为这个对象设定一个唯一的标识。而且你还需要去判断对象的类型，如果类型为TASK_TCP_RECV，则要在堆里去创建一个PRECVINFO对象，并且初始化这个PRECVINFO结构，并将指针赋与PTask->lprRecvInfo变量。

最后在消息的响应函数中调用PDefine::SCreateNewThread()静态方法，传递wParam

和lParam参数。

* * * * * * * * * * * * *

*消息名称： OMSG_MISSION_END

*类型：必需响应的消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* WPARAM wParam -表明了任务的完成状态。值为0时，表示任务已经完成。非0值，表示任务的当前状态。

* LPARAM lParam -指向PTask对象的指针

*说明：

* 表明一个PTask对象的任务已经完成或终止。

* * * * * * * * * * * * *

*消息名称： OMSG_NEW_TCP_CONNECTED

*类型：必需响应的消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* WPARAM wParam -用来得到SOCKET句柄的关键参数。

* LPARAM lParam -指向请求该连接的PFriend对象的指针

*说明：

* 一个由连接方请求的TCP连接被建立。关于该Socket的所有操作，将转移给DLL外部处理。在响应函数中需要调用PDefine::SGetSocketConnected(WPARAM wParam)静态方法，将wParam作为参数传递，来返回已经建立好TCP连接的SOCKET句柄。

* * * * * * * * * * * * *

*消息名称： OMSG_TCP_APPLY_CONNECTED

*类型：如果用到了TASK_TCP类型的连接，必需响应该消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* WPARAM wParam -已经建立好TCP连接的SOCKET句柄

* LPARAM lParam -指向建立连接的PFriend对象的指针

*说明：

* 一个请求的类型为TASK_TCP的TCP连接已经被成功的建立。

关于该Socket的所有操作，转移给DLL外部处理。

类型为TASK_TCP，表示对方也在使用这个DLL，你可以传送指令对象。

双方已经通过了身份校验。

* * * * * * * * * * * * *

*消息名称： OMSG_TCP_USER_APPLY_CONNECTED

*类型：如果使用了TASK_TCP_USER类型的连接，必需响应该消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* WPARAM wParam -已经建立好TCP连接的SOCKET句柄

* LPARAM lParam -指向建立连接的PFriend对象的指针

*说明：

* 一个请求的类型为TCP_USER_TYPE的TCP连接已经被成功的建立。

关于该Socket的所有操作，转移给DLL外部处理。

类型为TASK_TCP_USER，表示对方没有使用或不确定使用了这个DLL。

这个连接只是进行了创建，双方还没有进行任何的数据传送。

* * * * * * * * * * * * *

*消息名称： OMSG_A_RECV_THREAD_END

*类型：可以响应的消息。

*接收消息的窗体：

* 在PTask对象的m_lprMsgInfo变量所指的结构中定义的窗体。

*参数：

* WPARAM wParam -低8位表示该线程在PTask对象的线程组中的标识号

* LPARAM lParam -保存的是线程所在的PTask对象中的m_dwIdentify属性的值

*说明：

* 表明一个接收文件的线程结束。

* * * * * * * * * * * * *

*消息名称： OMSG_A_SEND_THREAD_END

*类型：可以响应的消息。

*接收消息的窗体：

* 在PTask对象的m_lprMsgInfo变量所指的结构中定义的窗体。

*参数：

* WPARAM wParam -低8位表示该线程在PTask对象的线程组中的标识号

* LPARAM lParam -保存的是线程所在的PTask对象中的m_dwIdentify属性的值

*说明：

* 表明一个传送文件的线程结束。

* * * * * * * * * * * * *

*消息名称： OMSG_CPATURE_SOUND_RELEASED

*类型：可以响应的消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* 无意义

*说明：

* 表明一个声音捕捉设备被释放，这个释放并不是调用

PDefine::SReleaseSoundCaptureDevice()方法而产生的。

* * * * * * * * * * * * *

*消息名称： OMSG_CHAT_CONNECT_CLOSED

*类型：可以响应的消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* LPARAM lParam -指向拥有该聊天连接的PFriend对象的指针

*说明：

* 表明lParam所指定的PFriend对象的聊天Socket被关闭。

* * * * * * * * * * * * *

*消息名称： OMSG_CHAT_CONNECT_CREATED

*类型：可以响应的消息。

*接收消息的窗体：

* 在PDefine::rSMsgInfo结构中定义的窗体。

*参数：

* LPARAM lParam -指向拥有该聊天连接的PFriend对象的指针

*说明：

* 表明一个聊天Socket被建立，并且已经连接到了好友对象上。

* * * * * * * * * * * * *

*消息名称： OMSG_CREATE_CONNECT_FAILED

*类型：可以响应的消息。

*接收消息的窗体：

* 在PTask对象的m_lprMsgInfo变量所指的结构中定义的窗体。

*参数：

* WPARAM wParam -错误的原因。查阅错误代码的枚举定义。

* LPARAM lParam -指向想建立连接的PFriend对象的指针

*说明：

* 表明与PFreind对象无法建立连接，在建立连接时产生了一个错误。

* * * * * * * * * * * * *

*消息名称： OMSG_MAX_THREAD_NO_CREATED

*类型：可以响应的消息。

*接收消息的窗体：

* 在PTask对象的m_lprMsgInfo变量所指的结构中定义的窗体。

*参数：

* LPARAM lParam -保存的是线程所在的PTask对象中的m_dwIdentify属性的值

*说明：

* 表明lParam所指的PTask对象已经创建了最大的线程个数。

* * * * * * * * * * * * *

*消息名称： OMSG_RECV_DATA

*类型：可以响应的消息。

*接收消息的窗体：

* 在PTask对象的m_lprMsgInfo变量所指的结构中定义的窗体。

*参数：

* WPARAM wParam -低8位表示该线程在PTask对象的线程组中的标识号

* LPARAM lParam -保存的是线程所在的PTask对象中的m_dwIdentify属性的值

*说明：

* 表明接收到了新的数据信息。

在消息的响应函数中，你需要设定PTask中的属性m_bIsSendMsg=true，否则无法再接收到该任务所发出的该消息。

在PTask中的m_dwCompletedSize属性中保存的是总的接收的字节数。

你可以调用PTask对象的GetThreadIDInArray((BYTE)wParam)来获得该线程所在的PTHREADID结构的指针。

* * * * * * * * * * * * *

*消息名称： OMSG_RECV_NEW_BLOCK

*类型：可以响应的消息。

*接收消息的窗体：

* 在PTask对象的m_lprMsgInfo变量所指的结构中定义的窗体。

*参数：

* WPARAM wParam -低8位表示该线程在PTask对象的线程组中的标识号

* LPARAM lParam -保存的是线程所在的PTask对象中的m_dwIdentify属性的值

*说明：

* 表明接收线程准备接收一个新分配的块号。

你可以调用PTask对象的GetThreadIDInArray((BYTE)wParam)来获得该线程所在的 PTHREADID结构的指针。

* * * * * * * * * * * * *

*消息名称： OMSG_SEND_DATA

*类型：可以响应的消息。

*接收消息的窗体：

* 在PTask对象的m_lprMsgInfo变量所指的结构中定义的窗体。

*参数：

* WPARAM wParam -低8位表示该线程在PTask对象的线程组中的标识号

* LPARAM lParam -保存的是线程所在的PTask对象中的m_dwIdentify属性的值

*说明：

* 表明传送了新的数据信息。

在消息的响应函数中，你需要设定PTask中的属性m_bIsSendMsg=true，否则无法再接收到该任务所发出的该消息。

在PTask中的m_dwCompletedSize属性中保存的是总的传送的字节数。

你可以调用PTask对象的GetThreadIDInArray((BYTE)wParam)来获得该线程所在的 PTHREADID结构的指针。

* * * * * * * * * * * * *

*消息名称： OMSG_SEND_NEW_BLOCK

*类型：可以响应的消息。

*接收消息的窗体：

* 在PTask对象的m_lprMsgInfo变量所指的结构中定义的窗体。

*参数：

* WPARAM wParam -低8位表示该线程在PTask对象的线程组中的标识号

* LPARAM lParam -保存的是线程所在的PTask对象中的m_dwIdentify属性的值

*说明：

* 表明传送线程准备传送一个新的部分。

你可以调用PTask对象的GetThreadIDInArray((BYTE)wParam)来获得该线程所在的 PTHREADID结构的指针。

十一 PPQ.DLL中定义的结构说明

*结构名称： PRECVINFO

*结构指针定义： LPRECVINFO

*属性:

* WORD wSplitNo -下载文件被分割的块数。如果设定分割块数为0， DLL会根据PDefine::dwSBlockMaxSize中的值自动计算分割块数。

* CString strSaveName -被保存的文件的名称和相对于基准路径的路径。如果strSaveName=_T("")，则文件名等于传送方的文件名。该属性的值可以包含一个"\"结尾的路径，这个路径是相对于基准路径的路径。例如"pict\"，表示在基准路径下的pict子目录下去建立文件。也可以直接写成"e:\pict\"，而设置基准路径为""。

* CString strSaveBasePath -表示被保存在本地的文件的基准路径。路径必需以"\"结尾。

* CString strExpendName -被保存文件的扩展名。扩展名不包括"."符号。如果缺省，等于请求的文件名的扩展名。

* CString strSrvURL -当类型为TASK_HTTP_RECV时，该属性必需赋值。表示要连接的服务器的URL地址。

* 下面这些属性的值由DLL在使用过程中填充，不要去修改这些值。

* CString strAddr -表示服务器的地址。

* UINT nPort -表示服务器的端口号。

* CString strFileN -表示要下载的文件名。

* CString strReferer -表示重定向已后的Referer的值。

* DWORD dwFileSize -文件的总的长度。

* DWORD dwBlockLen -每个块的长度。

* char* lpszBlockMap -保存每个分割块的状态。第一次调用时，赋值为空。

* DWORD dwLowDateTime -被下载的文件在传送方的最后修改日期的低32位。

* DWORD dwHighDateTime -被下载的文件在传送方的最后修改日期的高32位。

*说明：

* 当申请一个连接用于下载文件时，必需填写该结构，并且将指针传递给PTask中的m_lprRecvInfo变量。在创建该结构后，一定要使用以下方法初始化结构：

memset(m_lprRecvInfo,0,DWORD(&m_lprRecvInfo->nPort)-(DWORD)m_lprRecvInfo);

当类型为TASK_TCP_RECV时，所有的属性都可以缺省。

当类型为TASK_HTTP_RECV时，必需设定strSrvURL属性的值，表示想下载的文件的URL。

* * * * * * * * * * * * *

*结构名称： PTHREADID

*结构指针定义： LPPTHREADID

*属性:

* bool bIsSuspend -线程是否被挂起。挂起时为true。

* bool bIsRun -线程是否运行。运行时为true。

* PTask* PTask -当前线程所归属的线程组对象。

* int nBlockNo -线程当前被分配的块号。

* BYTE bySuffix -标识当前线程在线程组中的标识。

* CWinThread* pMyThread -指向这个线程的CWinThread对象的指针。

* SOCKET sock -传递给线程的已经创建好连接的SOCKET对象。

* CString strBlockFileN -当前分割块所对应的文件名。

* DWORD dwOffset -当前线程接收的起始偏移位置。这个偏移已经包含了被接收的长度。

* DWORD dwBlockLen -当前接收块应该接收的长度。

* DWORD dwCompletedLen -当前块已被接收或传送的长度。

* HANDLE hEvent -用来同步的事件句柄。

*说明：

* 在这个结构中的值，都由DLL在运行过程中填充，不要试图去修改这些值。

* * * * * * * * * * * * *

*结构名称： PMSGINFO

*结构指针定义： LPPMSGINFO

*属性:

* CWnd* pWnd -接收消息的窗口的指针。

* UINT nMsg -发送的消息的标识。

* bool bIsAutoDel -标识该结构是否被自动删除。如果值为false，需要你自己来删除。值为true时，表示该结构所归属的对象一旦被删除，该结构也被除。

*说明：

* 保存向用户发送消息时的窗口句柄和消息的标识。

十二 PDefine类中的静态函数说明

*函数名称：

* SApplyAnPDHANDLE()

*类型：

* 静态函数。

*参数:

* 无。

*返回值:

* PDHANDLE -对象的句柄。

*说明：

* 该函数返回一个用来处理数据流的对象的句柄。

* * * * * * * * * * * * *

*函数名称：

* SClosePDHANDLE();

*类型：

*参数:

* PDHANDLE handle -对象的句柄。

*返回值:

* 无。

*说明：

* 该函数关闭一个处理对象流的对象的句柄，以释放所占用的资源。

*函数名称：

* SCoalitionFile()

*类型：

* 静态函数。

*参数:

* LPCTSTR lpszSrcFileTitle -保存在本地的分割文件的文件标题。

* LPCTSTR lpszExpandN -文件的扩展名。

* LPCTSTR lpszBasePath -文件的基准路径。

* LPCTSTR lpszTargetFileN=NULL -合并后的文件的文件名。NULL时表示与块文件相同。

* bool bAutoDelete=true -在合并时是否自动删除块文件。

*返回值:

* DWORD -如果成功，返回0，否则低16位返回错误代码，高16位返回在第几个块文件发生错误。

*说明：

* 该函数将已下载完成的各个块文件合并成单个的文件。

当文件下载完成后，应该使用该函数来完成文件的合并，以确保对后续版本的支持。该函数会自动检测文件是否已全部下载完成，只有文件全部下载完成后，才会进行合并处理。

注意：对只有单个块的下载文件，会在下载完成后自动处理。

如果对单个块的下载文件调用该函数，会返回文件不存在的错误。

该函数是一个阻塞式的函数，如果在执行该函数时，不想望阻塞程序的执行，请在一个线程中去调用该函数。

* * * * * * * * * * * * *

*函数名称：

* SGetBlockFileName()

*类型：

* 静态函数。

*参数:

* LPCTSTR lpszSaveName -包含相对于基准路径的路径和文件标题。

* LPCTSTR lpszExtName -文件的扩展名。

* LPCTSTR lpszBasePath -保存块文件的基准路径。

* int nBlockNo -文件的分割块号。

* CString* pstrFileN -保存块文件的文件名的对象的指针。

*返回值:

* 无。

*说明：

* 该对象根据传递的参数形成块文件的文件名，并保存在pstrFileN对象中。

* * * * * * * * * * * * *

*函数名称：

* SGetSocketConnected()

*类型：

* 静态函数。

*参数:

* WPARAM wParam -消息的wParam参数。

*返回值:

* SOCKET -一个已经建立TCP连接的SOCKET句柄。

*说明：

* 在OMSG_NEW_TCP_CONNECTED消息的响应体中，调用该函数，并传递wParam参数，将返回一个已经建立TCP连接的SOCKET句柄。

* * * * * * * * * * * * *

*函数名称：

* SGetTime()

*类型：

* 静态函数。

*参数:

* LPCTSTR lpszTime -表示时间的字符串。

*返回值:

* CTime -该字符串所表示的时间对象。

*说明：

* 该函数将一个表示时间的字符串转换成CTime对象。

* * * * * * * * * * * * *

*函数名称：

* SRecvActObject()

*类型：

* 静态函数。

*参数:

* SOCKET sock -想接收数据流的SOCKET句柄。

* int& nCount -该次操作所接收到的数据的字节数。

* PDHANDLE handle -一个对象的句柄。

*返回值:

* PBaseAct* -如果接收到的数据流是一个指令对象，则返回指向该指令对象的指针。否则返回NULL。

*说明：

* 该函数去读取指定SOCKET的缓冲区中的数据，以形成指令对象。

注意: 从第一次接收数据，一直到指令的形成，都应该使用同一个PDHANDLE句柄，否则数据流无法正确接收，最好的办法是为每一个SOCKET连接去申请一个PDHANDLE句柄。PDHANDLE句柄可以通过调用SApplyAnPDHANDLE()方法得到，或者是DLL内部传递的句柄。

该方法是一个非阻塞方法，如果SOCKET缓冲区中没有可读取的数据，将立即返回。该方法不保证一次调用就会读取缓冲区中的所有数据，因此应在外部通过select()方法检测是否有可读取的数据或在OnReceive消息响应函数中调用该方法。

如果该函数执行后，nCount的值为0，表示没有读取到任何的数据。这时有可能SOCKET连接已经断开。

* * * * * * * * * * * * *

*函数名称：

* SSendFromSocket()

*类型：

* 静态函数。

*参数:

* SOCKET sock -一个已经建立TCP连接的SOCKET句柄。

* char* src -经过序列化的指令对象的数据流。

* WORD wLen -数据流的长度。

*返回值:

* 无。

*说明：

* 该函数将指令对象所表示的数据流通过指定的SOCKET发送出去。

注意：该SOCKET所连接的双方都必需在使用这个DLL来解析数据，否则发送出去的数据流对方是无法解析的。

src和wLen是你在调用指令对象的SelfSerialize()方法时传递的参数。

在SelfSerialize()方法中的dwLen参数，从DWORD被强制转换成WORD,表明在你序列化指令对象时的数据流长度不能超过65535。

如果你的数据流中要传送大型的数据，你可以在指令对象中使有CStringEx对象来保存大型的数据，使传送可以超过65535字节的任意大小的数据流。

（具体方法可以参照PBaseAct中的说明）

* * * * * * * * * * * * *

*函数名称：

* SGetSoundCaptureDeviceList()

*类型：

* 静态函数。与声音捕捉相关的函数。

*参数:

* HWND hCaptureDeviceCombo -CComboBox对象的m_hWnd属性的值。指定填充可利用的声音捕捉设备列表的组合框。参数值可以为NULL。CComboBox对象不要排序。

*返回值:

* 无

*说明：

* 该函数将控测可利用的声音捕捉设备名称，并填充在hCaptureDeviceCombo参数指定的CComboBox对象中。

* * * * * * * * * * * * *

*函数名称：

* SInitSoundCaptureDevice()

*类型：

* 静态函数。与声音捕捉相关的函数。

*参数:

* HWND hCaptureDeviceCombo -在SGetSoundCaptureDeviceList()方法中传递的参数。如果值为空，则dwIndex参数起作用。

* DWORD dwIndex=0 -指定选择探测到的第几个捕捉设备。如果第1个参数不为NULL，则该参数不起作用。

*返回值:

* UINT -成功则返回0值，否则为错误代码。当返回为错误代码时，声音捕捉设备被自动释放。

*说明：

* 初始化指定的捕捉设备用于声音捕捉。

* 注意：该函数在调用PDefine::SReleaseSoundCaptureDevice()方法之前，只能被执行一次。超过一次的执行，都会返回一个ERR_NO_CAPTURE_DEVICE错误。

在调用该方法前，可以由用户在CComboBox列表中选择指定的设备，待用户选定后，再调用该方法，该方法会提取用户的选择。

当第一个参数为NULL，第二个参数缺省时，表示选择检测到的第一个可利用设备。

* * * * * * * * * * * * *

*函数名称：

* SGetSoundCaptureAvailableFormats()

*类型：

* 静态函数。与声音捕捉相关的函数。

*参数:

* HWND hListBox -CListBox对象的m_hWnd属性的值。指定填充声音捕捉设备可利用的音频格式的列表框。参数可以为空。CListBox对象不要排序。

*返回值:

* 无

*说明：

* 该函数将检测选定的捕捉设备可利用的音频格式，并填充在hListBox参数指定的CListBox对象中。

* * * * * * * * * * * * *

*函数名称：

* SCreateSoundCaptureBuffer()

*类型：

* 静态函数。与声音捕捉相关的函数。

*参数:

* HWND hListBox -在SGetSoundCaptureAvailableFormats()方法中传递的参数。如果值为空，则dwIndex参数起作用。

* DWORD dwFormatsIndex=8 -指定选择检测到的第几个音频格式。如果第1个参数不为NULL，则该参数不起作用。

*返回值:

* UINT -成功则返回0值，否则为错误代码。当返回为错误代码时，声音捕捉设备被自动释放。

*说明：

* 为声音捕捉设备建立录音缓冲区。

注意：在调用该方法前，可以由用户在CListBox列表中选择指定的格式，待用户选定后，再调用该方法，该方法会提取用户的选择。

当第一个参数为NULL，第二个参数缺省时，表示选择缺省的音频格式。

缺省的音频格式为22.05KHz，8位，单通道，单声道格式。

* * * * * * * * * * * * *

*函数名称：

* SSetSoundCaptureAcceptdFriend()

*类型：

* 静态函数。与声音捕捉相关的函数。

*参数:

* PFriend* pFriend -好友对象的指针。

*返回值:

* 无

*说明：

* 该函数设定捕捉到的声音被传送给哪一个好友对象。

如果与该好友对象之间没有建立连接，则传送被忽略。

你可以在声音捕捉建立后的任何一个时间去调用这个函数。

* * * * * * * * * * * * *

*函数名称：

* SRecordSound()

*类型：

* 静态函数。与声音捕捉相关的函数。

*参数:

* UINT -成功则返回0值，否则为错误代码。当返回为错误代码时，声音捕捉设备被自动释放。

*返回值:

* 无

*说明：

* 开始进行声音捕捉。

* * * * * * * * * * * * *

*函数名称：

* SStopRecordSound()

*类型：

* 静态函数。与声音捕捉相关的函数。

*参数:

* 无

*返回值:

* UINT -成功则返回0值，否则为错误代码。当返回为错误代码时，声音捕捉设备被自动释放。

*说明：

* 暂时停止声音捕捉，这时声音捕捉设备并未被释放，你可以通过再次调用PDefine::SRecordSound()方法重新开始声音捕捉。

* * * * * * * * * * * * *

*函数名称：

* SReleaseSoundCaptureDevice()

*类型：

* 静态函数。与声音捕捉相关的函数。

*参数:

* 无

*返回值:

* 无

*说明：

* 停止捕捉声音，释放声音捕捉声备所占用的资源。

该函数是一个安全的函数，即使你没有成功创建声音捕捉设备，你仍然可以(应该)调用该函数，以确保声音捕捉设备被释放。

* * * * * * * * * * * * *

*函数名称：

* SPlaySound()

*类型：

* 静态函数。与声音回放相关的函数。

*参数:

* DWORD dwFormatsIndex=8 -播放声音的音频格式的索引。该索引与SGetSoundCaptureAvailableFormats()方法返回的索引是完全相同的。

*返回值:

* 无

*说明：

* 开始播放声音。调用该函数后，程序会自动从传送过来的声音缓冲区中取出数据，然后播放，如果缓冲区中没有数据，会播放静音。

注意：因为播放声音应该根据对方传递的录音格式来进行播放，因此，播放的格式实际上不需要去选择。

另外，在进行网际传输的过程中，将会根据线路质量，来动态的减少或增加音频采样频率，以达到最佳的效果，因此，每一段传送的音频的格式都可能不一样。

在传送声音数据的同时，已经包含了该次声音数据的格式，只是这一段切换播放声音格式的程序暂时没有实现。

* * * * * * * * * * * * *

*函数名称：

* SStopPlaySound()

*类型：

* 静态函数。与声音回放相关的函数。

*参数:

* 无

*返回值:

* 无

*说明：

* 暂时停止声音播放，这时声音回放设备的资源并没有释放。

可以通过调用PDefine::SPlaySound()方法继续声音回放。

* * * * * * * * * * * * *

*函数名称：

* SReleaseSoundPlayDevice()

*类型：

* 静态函数。与声音回放相关的函数。

*参数:

* 无

*返回值:

* 无

*说明：

* 停止声音回放，释放声音回放声备所占用的资源。

该函数是一个安全的函数，即使你没有成功创建声音回放设备，你仍然可以(应该)调用该函数，以确保声音回放设备被释放。

* * * * * * * * * * * * *

*函数名称：

* SCreateNewObj()

*类型：

* 静态函数。

*参数:

* WPARAM wParam -消息的wParam参数。

* LPARAM lParam -消息的lParam参数。

*返回值:

* 无

*说明：

* 在接收到OMSG_CREATE_NEW_OBJ消息时，才需要调用该函数。该函数的2个参数就是消息响应函数的2个参数。

* * * * * * * * * * * * *

*函数名称：

* SCreateNewThread()

*类型：

* 静态函数。

*参数:

* WPARAM wParam -消息的wParam参数

* LPARAM lParam -消息的lParam参数

*返回值:

* 无

*说明：

* 在OMSG_CREATE_NEW_THREAD消息的响应函数的最后，调用该方法。该函数的2个参数就是消息响应函数的2个参数。

* * * * * * * * * * * * *

*函数名称：

* SCreateTCPListenPort()

*类型：

* 静态函数。

*参数:

* UINT nPort -监听端口的端口号

*返回值:

* bool -如果成功的创建了监听端口，则返回true。否则返回false。

*说明：

* 创建一个TCP监听端口。

该函数只能被运行一次，超过一次的运行将不作任何操作，并始终返回true。

后续版本的支持：在后续的版本中，将允许创建多个监听端口，在DLL内部会维护一个已经创建的监听端口的列表。

* * * * * * * * * * * * *

*函数名称：

* SGetSelfUserID()

*类型：

* 静态函数。

*参数:

* CString* pstrID -保存当前用户ID的对象的指针。

*返回值:

* 无

*说明：

* 将当前用户ID复制到传递的参数中。当前用户的ID被保存在PDefine::szSelfFriendID变量中。

* * * * * * * * * * * * *

*函数名称：

* SInitSocketStream()

*类型：

* 静态函数。

*参数:

* 无

*返回值:

* bool -如果初始化win socket库成功，则返回true。

*说明：

* 初始化win socket库和内部的一些工作线程。在程序开始前必需先调用该方法。

* * * * * * * * * * * * *

*函数名称：

* SNotifyConnectSrc()

*类型：

* 静态函数。

*参数:

* PDHANDLE handle -解析该指令的PDHANDLE对象的句柄。该句柄可通过指令对象的GetCallBackPointer()方法得到。

* DWORD dwFlag -希望SOCKET作出的动作。取值是枚举中定义的以ACT_打头的常量。

*返回值:

* 无

*说明：

自定义对象回调传送指令的Socket连接对象，指示Socket作出相应的动作。这个函数只有在自定义对象的处理函数中发现指令对象传递了错误的信息，需要关闭连接时才需要调用。

* * * * * * * * * * * * *

*函数名称：

* SRemoveUserGetObjectFunHook()

*类型：

* 静态函数。

*参数:

* GOCALLBACK pFun -指向要取消的钩子(回调)函数的指针。

*返回值:

* 无

*说明：

* 摘除原先设定的返回开发者自定义对象的CRuntimeClass结构的指针的钩子函数。

如果钩子函数原先没有被设定，函数不执行任何操作。

* * * * * * * * * * * * *

*函数名称：

* SSetUserGetObjectFunHook()

*类型：

* 静态函数。

*参数:

* GOCALLBACK pFun -指向要增加的钩子(回调)函数的指针。

*返回值:

* 无

*说明：

* 设置返回开发者自定义对象的CRuntimeClass*指针的钩子(回调)函数。

如果要增加的钩子函数已经被加入了，将不再重复增加这个钩子函数。

注意：每一个开发者都应该独立的设定自己的钩子函数来返回自定义对象的CRuntimeClass结构的指针。

其他开发者通过调用SSetUserGetObjectFunHook()函数来增加你的钩子函数。

十三 PDefine类中的静态属性

*属性定义：

* bool bSIsReleaseVer

*类型：

* 静态。缺省值=true。

*说明：

* 表明当前的运行程序是否是正式版本。

如果该值为false，则可以进行单机的连接测试。

在单机测试时，被连接方将返回一个固定的ID号"PPQ000000000"。

如果你需要与其它程序相连，则必需设定该值为true。

* * * * * * * * * * * * *

*属性定义：

* DWORD dwSBlockMaxSize

*类型：

* 静态。缺省值=5*1024*1024=5M bytes。

*说明：

* 当接收一个文件时，如果没有指定分割块的个数，DLL会按照该值来决定一个块的最大尺寸。

* * * * * * * * * * * * *

*属性定义：

* GETPALCALLBACK pSGetFriendCallBackFun

*类型：

* 静态。这个属性必需在开始时就赋于一个正确的回调函数的地址。不能为NULL。

*说明：

* 保存回调函数的指针，通过向这个函数传递好友的ID来得到该ID所对应的PFriend对象的指针。

* * * * * * * * * * * * *

*属性定义：

* GETFILENCALLBACK pSGetFileNCallBackFun

*类型：

* 静态。这个函必需在开始时就赋于一个正确的回调函数的地址。不能为NULL。

*说明：

* 保存回调函数的指针，通过向这个函数传递一个文件的数字标识来得到实际的文件名。

* * * * * * * * * * * * *

*属性定义：

* PMSGINFO rSMsgInfo

*类型：

* 静态。这个属性必需在开始时就赋于一个有效的值。

*说明：

* 定义接收DLL发送的一些重要消息的接收窗体。这个结构必需被赋值。

* * * * * * * * * * * * *

*属性定义：

* char szSelfFriendID[USER_ID_LEN+1]

*类型：

* 静态。这个属性必需在开始时就赋于一个有效的值。

*说明：

* 自已的ID号。这个值在很多情况下都会被读取，必需在DLL开始后首先赋值。

* * * * * * * * * * * * *

*属性定义：

* WORD wSendMsgRate;

*类型：

* 静态。缺省值=100。

*说明：

* 表示接收或传送线程中向外发送OMSG_RECV_DATA或OMSG_SEND_DATA消息时的缺省速率。

值越大，发送消息次数越少，值越小，发送消息的次数越多。

缺省值的情况下，大约每接收或传送到400K数据时，发送一次消息。