Stream Server SDK Programmer s Manual V2.0. Stream Server SDK Programmer s Manual V 2.0

Transcription

1 Stream Server SDK Programmer s Manual V 2.0

2 Index 1. Summary Stream Server System SDK Stream Media Server SDK Stream Client SDK DLL Interface Callback Function Set Transmit Server SDK Application Development Server Application Development API Calls Order Compilation Link Client Application Development API Calls Order The Definition of the Callback Function Compilation Link Writing Sample... 17

3 1. Summary Streaming Server SDK packages the streaming server establishment related bottom order data and the streaming data transmission. For the upper application, it masks the specific transmission process. Meanwhile, it has a good scalability for the Lower different equipment drive and the different media format player. 1

4 2. Stream Server System SDK 2.1 Stream Media Server SDK The definition of the API function derived by DLL in the server.h document, as bellowing: 1. SERVER_API int InitStreamServerLib(void) Function: Initialization ACE. The function is required to be called when the window procedure is being initialized. 2. SERVER_API int FiniStreamServerLib(void) Function: Close ACE. The function is required to be called when the window procedure is being closed. 3. SERVER_API int StartServer(const char* path,unsigned short port = 554) Function: Initialization Server. Path pointing directory path of the streaming file. Port refers to the interception port of the server, with the default value of SERVER_API int RunServer() Function: It runs server processing threads and can receive and process the requests from clients. This function returns immediately after opening the server threads. 5. SERVER_API int RunServerLoop() Function: It runs server processing threads and can receive and process the requests from clients. This function plugs immediately after opening the server threads, and won t return before the end of the server threads. Returns: 0 6. SERVER_API int StopServer() Function: Stop service and release the resources. 7. SERVER_API int GetServerState() Has not being used yet. 8. SERVER_API int GetCurConnnection() Function: Returns the current number of client connections. 2

5 Returns: The current number of client connections. 9. SERVER_API int GetCurChannel() Function: Returns the number of current connecting equipment channels. Returns: The number of current connecting equipment channels. 10. SERVER_API int VodCreateIndex(char* filename,int len) Function: Creates essential file indexes for VOD files player. 11. SERVER_API int stdcall SetNewConnectionCallBack (CBF_NotifyANewConnection callback) Function: Set up client/ Disconnect news callback function. Returns: 0 The callback function: The form of the callback function is: typedef int ( stdcall *CBF_NotifyANewConnection)(bool badd, const char* clientip, unsigned short port, const char* url) Among that, false for badd means disconnect one client, meanwhile,url means NULL, and true means add a client. 3

6 2.2 Stream Client SDK DLL Interface The definition of DLL derived API function in the header file of client.h, as following: 1. CLIENT_API int stdcall InitStreamClientLib(void) Function: Initialization ACE. The function is required to be called when the window procedure is being initialized. 2. CLIENT_API int stdcall FiniStreamClientLib(void) Function: Close ACE. The function is required to be called when the window procedure is being closed. 3. CLIENT_API HSESSION stdcall HIKS_CreatePlayer (IHikClientAdviseSink* psink, void* pwndsitehandle, pdatarec precfunc, pmsgback pmsgfunc=0, int TransMethod=0) Function: Create player. psink is the type set pointer of callback functions. pwndsitehandle is the window handle. Cfun is the callback function pointer. If NULL for pwndsitehandle, it means no video. pmsgfunc is the information callback function handle. It has the same FUNC with the callback function set which is expressed by the first parameter psink, but the different forms. pmsgfunc and psink could not be null at the same time. TransMethod express the media data transmission method. 0 for TCP, 1 for UDP, and the default for TCP. However, if on the environment of LAN, UDP is suggested. The callback function: (i) IHikClientAdviseSink: refer to for the callback function (ii) pdatarec typedef int ( stdcall *pdatarec)(int sid, int iusrdata, int idatatype, char* pdata, int ilen). sid means Session ID. iusrdata temporarily without useless. idatatype means the data type of the callback function. 0 is the first data. 1 means the streaming data. pdata is a indicator of data which has been call backed. (iii) pmsgback typedef int ( stdcall *pmsgback)(int opt, int param1, int param2). opt means the type of the information. param1 and param2 determine their effectiveness according to the information types. Different opt counterparts different callback function of the callback function set IHikClientAdviseSink: opt Callback Function param1 param2 1 OnPosLength nlength dimmed 4

7 -1. 2 OnPresentationOpened success dimmed 3 OnPresentationClosed dimmed dimmed 4 OnPreSeek uoldtime unewtime 5 OnPostSeek uoldtime unewtime 6 OnStop dimmed dimmed 7 OnPause utime dimmed 8 OnBegin utime dimmed 9 OnRandomBegin utime dimmed 10 OnContacting pszhost dimmed 11 OnPutErrorMsg perror dimmed 12 OnBuffering uflag upercentcomplete 13 OnChangeRate flag dimmed 14 OnDisconnect dimmed dimmed Returns: if success, returns the new player marker (int types, >=0); if failure, returns 4. CLIENT_API int stdcall HIKS_OpenURL(HSESSION hsession,const char* pszurl) Function: according to URL, connect server. hsession,the marker of the Player, must be set as the marker of the new player which is successfully returned from HIKS_CreatePlayer. pszurl is the address of the server. URL Format: URL Standard Format: VOD Relative path: rtsp://stream media server address:stream media server port/filename e.g. rtsp:// /stream.264 (If there is no port after the streaming server address, the default port is 554.) Absolute path: rtsp:// streaming media server address:streaming media server port/file absolute path. Live Streaming e.g. rtsp:// /d:/hikstream/files/stream.264 rtsp://stream media server address:stream media server port /equipment address: equipment port equipment type: main channel number: Deputy Number:user name: passport/av_stream e.g. rtsp:// / :8000:hik-ds8000hc:0:0:admin:12345/ av_stream 5

8 VOD Second Transmit Server Stream Server SDK Programmer s Manual V2.0 Relative path: rtsp://transmit server address: transmit server port/stream media server address: stream media server port/filename e.g.rtsp:// :556/ /stream.264 Absolute path: rtsp://transmit server address: transmit server port/stream media server address: stream media server port//file absolute path e.g.rtsp:// :556/ /d:/hikstream/files/stream.264 Live Second Transmit Server rtsp://transmit server address: transmit server port /stream media server address: stream media server port /equipment IP: equipment port: equipment type: main channel number: deputy channel number: user name: passport/av_stream e.g.rtsp:// :556/ / :8000:hik-ds8000 HC:0:0:admin:12345/av_stream 5. CLIENT_API int stdcall HIKS_Play(HSESSION hsession) Function: play. hsession is the player marker. 6. CLIENT_API int stdcall HIKS_RandomPlay(HSESSION hsession, unsigned long timepos) Function: Random player, for the video s driving around. hsession is the player marker. 7. CLIENT_API int stdcall HIKS_Pause(HSESSION hsession) Function: Pause player. hsession is the player marker. 8. CLIENT_API int stdcall HIKS_Resume(HSESSION hsession) Function: Recovery player. hsession is the player marker. 9. CLIENT_API int stdcall HIKS_Stop(HSESSION hsession) Function: Stop and destroy player. hsession is the player marker. This function is used when player failed or stopping is needed during player. After calling the function do not need to call HIKS Destroy. 10. CLIENT_API unsigned int stdcall HIKS_GetCurTime(HSESSION hsession, unsigned long *utime) Function: Access the current player time, with the unit of 1/64second. hsession is the player marker. utime express the current player time. 6

9 11. CLIENT_API int stdcall HIKS_ChangeRate(HSESSION hsession, int scale) Function: Change the rate of player. Used when FF or slow player. 12. CLIENT_API int stdcall HIKS_Destroy(HSESSION hsession) Function: Destroy player. It is only used when HIKS_OpenURL failed. 13. CLIENT_API int stdcall HIKS_GetVideoParams(HSESSION hsession, int *ibri, int *icon, int *isat, int *ihue) Function: Access video parameters. hsession is the player marker. ibri is the brightness. ion is the contrast. isat is the saturation. ihue is the hue. Range of value: ibri 0-255, icon 0-255, isat 0-255, ihue This function is only effective when the real-time streaming is player. 14. CLIENT_API int stdcall HIKS_SetVideoParams(HSESSION hsession, int ibri, int icon, int isat, int ihue) Function: Set video parameters. hsession is the Player marker. ibri is the brightness. ion is the contrast. isat is the saturation. ihue is the hue. Range of value: ibri 0-255, icon 0-255, isat 0-255, ihue This function is only effective when the real-time streaming is player. 15. CLIENT_API int stdcall HIKS_PTZControl(HSESSION hsession, unsigned int ucommand, int iparam1, int iparam2, int iparam3, int iparam4) Function: PTZ control. hsession is the Player marker. The meanings of the following 5 parameters are the same to the meanings of the last 5 parameters of cli_dvr_ptzcontrol in the Instruction Book02-Interface Specification-Equipment Server Abstrution Layer.doc. PTZ control commends code and the parameter definition are the same to that in DVRClientAPI.h of Abstruction Layer-Equipment Server Abstruction Layer. 7

10 16. CLIENT_API int stdcall HIKS_SetVolume(HSESSION hsession, unsigned short volume) Function: Set volume. hsission is the player marker. Range of volume: 0~ CLIENT_API int stdcall HIKS_OpenSound(HSESSION hsession) FUNC: Open the phone. hsession is the Player marker. 18. CLIENT_API int stdcall HIKS_CloseSound(HSESSION hsession) Function: Close the phone. hsession is the Player marker. 19. CLIENT_API int stdcall HIKS_ThrowBFrameNum(HSESSION hsession, unsigned int nnum) Function: Set ThrowBFrame player. hsession is the Player marker. nnum is the number of ThrowBFrame. 20. CLIENT_API int stdcall HIKS_GrabPic(HSESSION hsession, const char* szpicfilename, unsigned short bypictype); Function: Capture picture on player. hsession is the Player Marker. szpicfilename is for file name on saving. PicType is for selecting picture format saved, where 0 stands for bmp, and 1 stands for jpg. 8

11 2.2.2 Callback Function Set Callback functions are packed in the class of class IHikClientAdviseSink. This class is defined in the front file clntsink.h. These callback functions must be called in the window procedure of client.dll. Callback functions as follows: 1. virtual int OnPosLength(unsigned long nlength ) = 0 Function: Access the total length of player. nlength is the total length of player, with the unit of 1/64seconds. If the nlength is -1, it is means what has been received is the real-time streaming. Calls: Calls when setup. 2.virtual int OnPresentationOpened(int success) = 0 Function: Inform whether the URL has been opened successfully.if the success is 1, it is means success. If the success is 2, it is means failure. Calls: Calls when setup. 3.virtual int OnPresentationClosed() = 0 Function: Inform that the windows player has been closed. Calls: Calls when the player has been stopped and destroyed. 4.virtual int OnPreSeek( unsigned long uoldtime, unsigned long unewtime ) = 0 It has not been used yet. 5.virtual int OnPostSeek( unsigned long uoldtime, unsigned long unewtime ) = 0 It has not been used yet. 6.virtual int OnStop() = 0 It has not been used yet. 7. virtual int OnPause( unsigned long utime ) = 0 Function: Inform the windows players have been paused. utime is currently 0. Calls: Calls when the player has been paused. 8.virtual int OnBegin( unsigned long utime ) = 0 Function: Inform the window player s beginning. utime are currently 0. Calls: Calls when players begin. 9.virtual int OnRandomBegin( unsigned long utime ) = 0 Function: Inform the window random players begin. utime are currently 0. Calls: Calls when random player. 10.virtual int OnContacting( const char* pszhost ) = 0 Function: Inform the connecting server with the window. pszhost pointing the server IP address. 9

12 Calls: Calls when setuping. Stream Server SDK Programmer s Manual V virtual int OnPutErrorMsg( const char* perror ) = 0 Function: Inform the window server returns the error message. pszhost the contents of the error message. Calls: Calls when the server returns the error message. 12.virtual int OnBuffering( unsigned int uflag, unsigned short upercentcomplete ) = 0 It has not been used yet. 13. virtual int OnChangeRate(int flag)=0 Function: Inform the player rate has been changed. If flag>0, it is means the player rate has been doubled. If flag<0, it is means the player rate has been decrease by half. The maximum rate is the 8 times of the normal rate, and the minimum rate is 1/8 of the normal one. Calls: Calls when the server returns error messages. 14. virtual int OnDisconnect()=0 Function: Inform the window has lost the connection with the server. Received this notice, HIKS_Stop is needed to be called to stop the destruction of the player but couldn t be called Calls: calls if the client can t receive the server s returning within 20 seconds. 10

13 2.3 Transmit Server SDK The definition of the mrserver.dll derived API function is in the header file of mrserver.h, as follows: 1. SERVER_API int MR_InitStreamServerLib (void) Function: Initialization ACE. This function is called when the window program is initialized. 2. SERVER_API int MR_FiniStreamServerLib (void) Function: Close ACE. This function is called when the window program is closed. 3. SERVER_API int MR_StartServer(unsigned short port = 556); Function: Initialize server. port is the server monitor port, whose default value is SERVER_API int MR_RunServer () Function: Operate server processing threads. Receiving and processing the requests from client. 5. SERVER_API int MR_RunServerLoop () Function: Operate server processing threads. Receiving and processing the requests from client. This function will be plugged after opening the server threads and will not return until the ending of the server threads. Returns: returns SERVER_API int MR_StopServer () Function: Stop server and release the resources. 7. SERVER_API int MR_GetServerState () It has not being used yet. 8. SERVER_API int MR_GetCurConnection () Function: Access the number of currently connecting clients. Returns: returns the number of currently connecting clients. 11

14 3. Application Development 3.1 Server Application Development API Calls Order InitStreamClientLib StartServer RunServer StopServer FiniStreamClientLib First of all, calls InitStreamClientLib to initialize ACE and then activate streaming service. After calling StartServer to initialize server, we set local streaming file path and call RunServer to startup the service. If we need to sign-off server, we can call StopServer to stop the service and call FiniStreamClientLib to close ACE. 12

15 3.1.2 Compilation Link The following areas need attention: 1. Need to include server.h header file 2. Need to use server.lib 13

16 3.2 Client Application Development API Calls Order The above chart shows the five states the client on. OUT: Uninitialized ACE Network Environment STOP: State of stop INIT: State of initialization. URL has been opend. PLAY: State of playing PAUSE: State of pausing 14

17 Firstly, we call InitStreamClientLib to initialize ACE and enter the state of stop. After calling HIKS_CreatePlayer and HIKS_OpenURL, it enters the state of INIT. Then we call HIKS_Play to enter the state of play. At the state of playing, we can call HIKS_ChangeRate,HIKS_GetCurTime,and HIKS_RandomPlay, while the client is still at the state of playing. At the state of playing, we can call HIKS_Pause to convert to the state of pausing. At the state of pausing, we can call HIKS_Resume to convert back to the state of playing. At the state of INIT, playing and pause, we can call HIKS_Stop to return to the state of rest. Finally, we can call FiniStreamClientLib to close ACE. The following areas need special note: 1. If it s real-time streaming, HIKS_ChangeRate, HIKS_GetCurTime, HIKS_RandomPlay, HIKS_Resume and HIKS_Pause are all meaningless. At the same state, pause is also meaningless. 2. After calling HIKS_OpenURL, we can t call HIKS_Play instantly to play even though the returned value indicates success. Instead of that, we need to wait for int OnPresentationOpened(int success) being called and the 1 for success of the bring back parameter, then we can call HIKS_Play. 3. If HIKS_OpenURL has being called and returned failure or the parameter which has being brought back by OnPresentationOpened indicate failure, we need to call HIKS_Destroy to release the resources. But pls attention that don t call HIKS_Stop to release resources. 15

18 3.2.2 The Definition of the Callback Function On the application program, all the pure virtual functions in the IHikClientAdviseSink class must be achived Compilation Link The following areas need attention: 1. Need to include header files client.h and clntsink.h 2. Need to link client.lib 16

19 3.2.4 Writing Sample The Following sample is about using streaming client to write a playback function: void CclientTestDlg::OnBtnPlay() // CclientTestDlg is a dialog box class { int nret; if(m_hsession>=0) //m_hsession is a player marker. If m_hsession>=0, it is means there are some //players have been opened. //Firstly, we call HIKS_Stop to stop the dialog, release the resourses and set -1 for m_hsession. { nret=hiks_stop(m_hsession); //m_opened is also be set as -1, which will be used on the posterior asynchronous //operations. m_hsession = -1; m_opened=-1; } HWND hwnd = GetDlgItem(IDC_STATIC_SHOW)->GetSafeHwnd(); // Access the window handle m_hsession = HIKS_CreatePlayer(this,hWnd,NULL); //Create Player. Pls set the third parameter as NULL. //The fourth parameter is not written, by default NULL //The fifth parameter is not written, by default NULL if ( m_hsession!= -1 ) { nret = HIKS_OpenURL(m_hSession,m_URLvalue.GetBuffer(0),0); // Open URL. Pls set the third parameter as 0. if(nret!=1) { HIKS_Destroy(m_hSession); // After opening URL and returning failure, pls call HIKS_Destroy //to destroy player. m_hsession=-1; // Replace the variable value. m_opened=-1; return; } } while(m_opened<0) Sleep(100); // After opening URL, you can t play immediately but to wait for the //signal of m_opened. //The initial value of m_opened has been set as -1. //When the value of m_opened converted to a number which is not less than //0 or the time of waiting is long enough, it exits the loop. if(m_opened<=0) 17

20 { HIKS_Destroy(m_hSession); // When the value of m_opened not more than 0, it is means last step HIKS_OpenURL failed. //Although the direct return value didn t indicate the failure, it is still needed to be treated as //failure. m_hsession=-1; m_opened=-1; return ; } nret=hiks_play(m_hsession); // When the value of m_opened is 1, we can call HIKS_Play to play. if(nret!=1) // If the player failed, please attention that we should call HIKS_Stop to release the resources, //instead of opening the function which is called by URL by fail. { HIKS_Stop(m_hSession); m_hsession=-1; m_opened=-1; return ; } } // Window class need carry on IHikClientAdviseSink and to achieve its definition of the pure virtual callback function class CclientTestDlg : public CDialog, public IHikClientAdviseSink { public: int m_hsession; // It is defined as m_hsession and m_opened at the class. int m_opened; } BOOL CclientTestDlg::OnInitDialog() { m_hsession=-1; // Initiate m_hsession and m_opened to -1. m_opened=-1; } int CclientTestDlg::OnPresentationOpened(int success) { m_opened=success; // return 0; // m_opened is placed at OnPresentationOpened. If the value of success is 1, it is //means URL opening is successful. If the value is 0, it is means URL opening is failed. } 18