diff --git a/upnp/src/inc/ssdplib.h b/upnp/src/inc/ssdplib.h index 4690c7e..91c73af 100644 --- a/upnp/src/inc/ssdplib.h +++ b/upnp/src/inc/ssdplib.h @@ -1,3 +1,6 @@ +#ifndef SSDPLIB_H +#define SSDPLIB_H + /************************************************************************** * * Copyright (c) 2000-2003 Intel Corporation @@ -29,22 +32,21 @@ * **************************************************************************/ -#ifndef SSDPLIB_H -#define SSDPLIB_H +/*! + * \file + */ #include "httpparser.h" #include "httpreadwrite.h" #include "miniserver.h" #include "UpnpInet.h" - #include #include #include #include #include - #ifdef WIN32 #else /* WIN32 */ #include @@ -58,8 +60,7 @@ #include #endif /* WIN32 */ - -/* Enumeration to define all different types of ssdp searches */ +/*! Enumeration to define all different types of ssdp searches */ typedef enum SsdpSearchType{ SSDP_SERROR=-1, SSDP_ALL,SSDP_ROOTDEVICE, @@ -68,8 +69,7 @@ typedef enum SsdpSearchType{ SSDP_SERVICE } SType; - -/* Enumeration to define all different type of ssdp messages */ +/*! Enumeration to define all different type of ssdp messages */ typedef enum SsdpCmdType{ SSDP_ERROR=-1, SSDP_OK, @@ -80,9 +80,6 @@ typedef enum SsdpCmdType{ SSDP_TIMEOUT } Cmd; - - -/* Constant */ #define BUFSIZE 2500 #define SSDP_IP "239.255.255.250" #define SSDP_IPV6_LINKLOCAL "FF02::C" @@ -92,44 +89,45 @@ typedef enum SsdpCmdType{ #define THREAD_LIMIT 50 #define COMMAND_LEN 300 -/* can be overwritten by configure CFLAGS argument */ +/*! can be overwritten by configure CFLAGS argument. */ #ifndef X_USER_AGENT -/** @name X_USER_AGENT - * The {\tt X_USER_AGENT} constant specifies the value of the X-User-Agent: - * HTTP header. The value "redsonic" is needed for the DSM-320. See - * https://sourceforge.net/forum/message.php?msg_id=3166856 for more - * information - */ - #define X_USER_AGENT "redsonic" + /*! @name X_USER_AGENT + * The {\tt X_USER_AGENT} constant specifies the value of the X-User-Agent: + * HTTP header. The value "redsonic" is needed for the DSM-320. See + * https://sourceforge.net/forum/message.php?msg_id=3166856 for more + * information + */ + #define X_USER_AGENT "redsonic" #endif -/* Error code */ +/*! Error codes. */ #define NO_ERROR_FOUND 0 #define E_REQUEST_INVALID -3 #define E_RES_EXPIRED -4 #define E_MEM_ALLOC -5 #define E_HTTP_SYNTEX -6 #define E_SOCKET -7 + #define RQST_TIMEOUT 20 /*! Structure to store the SSDP information */ typedef struct SsdpEventStruct { - enum SsdpCmdType Cmd; - enum SsdpSearchType RequestType; - int ErrCode; - int MaxAge; - int Mx; - char UDN[LINE_SIZE]; - char DeviceType[LINE_SIZE]; - /* NT or ST */ - char ServiceType[LINE_SIZE]; - char Location[LINE_SIZE]; - char HostAddr[LINE_SIZE]; - char Os[LINE_SIZE]; - char Ext[LINE_SIZE]; - char Date[LINE_SIZE]; - struct sockaddr *DestAddr; - void * Cookie; + enum SsdpCmdType Cmd; + enum SsdpSearchType RequestType; + int ErrCode; + int MaxAge; + int Mx; + char UDN[LINE_SIZE]; + char DeviceType[LINE_SIZE]; + /* NT or ST */ + char ServiceType[LINE_SIZE]; + char Location[LINE_SIZE]; + char HostAddr[LINE_SIZE]; + char Os[LINE_SIZE]; + char Ext[LINE_SIZE]; + char Date[LINE_SIZE]; + struct sockaddr *DestAddr; + void * Cookie; } Event; typedef void (* SsdpFunPtr)(Event *); @@ -139,46 +137,42 @@ typedef Event SsdpEvent ; /*! Structure to contain Discovery response. */ typedef struct resultData { - struct Upnp_Discovery param; - void *cookie; - Upnp_FunPtr ctrlpt_callback; + struct Upnp_Discovery param; + void *cookie; + Upnp_FunPtr ctrlpt_callback; } ResultData; - typedef struct TData { - int Mx; - void * Cookie; - char * Data; - struct sockaddr_storage DestAddr; - + int Mx; + void * Cookie; + char * Data; + struct sockaddr_storage DestAddr; } ThreadData; typedef struct ssdpsearchreply { - int MaxAge; - UpnpDevice_Handle handle; - struct sockaddr_storage dest_addr; - SsdpEvent event; - + int MaxAge; + UpnpDevice_Handle handle; + struct sockaddr_storage dest_addr; + SsdpEvent event; } SsdpSearchReply; typedef struct ssdpsearcharg { - int timeoutEventId; - char * searchTarget; - void *cookie; - enum SsdpSearchType requestType; + int timeoutEventId; + char * searchTarget; + void *cookie; + enum SsdpSearchType requestType; } SsdpSearchArg; typedef struct { - http_parser_t parser; - struct sockaddr_storage dest_addr; + http_parser_t parser; + struct sockaddr_storage dest_addr; } ssdp_thread_data; - /* globals */ #ifdef INCLUDE_CLIENT_APIS @@ -189,399 +183,288 @@ typedef struct #endif /* INCLUDE_CLIENT_APIS */ typedef int (*ParserFun)(char *, Event *); +/*! + * \brief Make ssdp socket non-blocking. + * + * \return 0 if successful, -1 otherwise. + */ +int Make_Socket_NoBlocking( + /* [in] socket. */ + SOCKET sock); -/************************************************************************ -* Function : Make_Socket_NoBlocking -* -* Parameters: -* IN int sock: socket -* -* Description: -* This function to make ssdp socket non-blocking. -* -* Returns: int -* 0 if successful else -1 -***************************************************************************/ -int Make_Socket_NoBlocking (SOCKET sock); - -/************************************************************************ -* Function : ssdp_handle_device_request -* -* Parameters: -* IN void *data: -* -* Description: -* This function handles the search request. It do the sanity checks of -* the request and then schedules a thread to send a random time reply ( -* random within maximum time given by the control point to reply). -* -* Returns: void * -* 1 if successful else appropriate error -***************************************************************************/ +/*! + * \brief Handles the search request. It does the sanity checks of the + * request and then schedules a thread to send a random time reply + * (random within maximum time given by the control point to reply). + */ #ifdef INCLUDE_DEVICE_APIS void ssdp_handle_device_request( - IN http_message_t *hmsg, - IN struct sockaddr *dest_addr); + /* [in] . */ + http_message_t *hmsg, + /* [in] . */ + struct sockaddr *dest_addr); #else static inline void ssdp_handle_device_request( - IN http_message_t *hmsg, - IN struct sockaddr* dest_addr) {} + /* [in] . */ + http_message_t *hmsg, + /* [in] . */ + struct sockaddr* dest_addr) {} #endif -/************************************************************************ -* Function : ssdp_handle_ctrlpt_msg -* -* Parameters: -* IN http_message_t* hmsg: SSDP message from the device -* IN struct sockaddr* dest_addr: Address of the device -* IN int timeout: timeout kept by the control point while sending -* search message -* IN void* cookie: Cookie stored by the control point application. -* This cookie will be returned to the control point -* in the callback -* -* Description: -* This function handles the ssdp messages from the devices. These -* messages includes the search replies, advertisement of device coming -* alive and bye byes. -* -* Returns: void -* -***************************************************************************/ +/*! + * \brief This function handles the ssdp messages from the devices. These + * messages includes the search replies, advertisement of device coming alive + * and bye byes. + */ void ssdp_handle_ctrlpt_msg( - IN http_message_t *hmsg, - IN struct sockaddr *dest_addr, - IN int timeout, - IN void *cookie); + /* [in] SSDP message from the device. */ + http_message_t *hmsg, + /* [in] Address of the device. */ + struct sockaddr *dest_addr, + /* [in] timeout kept by the control point while sending search message. */ + int timeout, + /* [in] Cookie stored by the control point application. This cookie will + * be returned to the control point in the callback. */ + void *cookie); -/************************************************************************ -* Function : unique_service_name -* -* Parameters: -* IN char *cmd: Service Name string -* OUT SsdpEvent *Evt: The SSDP event structure partially filled -* by all the function. -* -* Description: -* This function fills the fields of the event structure like DeviceType, -* Device UDN and Service Type -* -* Returns: int -* 0 if successful else -1 -***************************************************************************/ -int unique_service_name(char * cmd, SsdpEvent * Evt); +/*! + * \brief Fills the fields of the event structure like DeviceType, Device UDN + * and Service Type. + * + * \return 0 if successful else -1. + */ +int unique_service_name( + /* [in] Service Name string. */ + char *cmd, + /* [out] The SSDP event structure partially filled by all the + * function. */ + SsdpEvent *Evt); + +/*! + * \brief Creates the ssdp sockets. It set their option to listen for + * multicast traffic. + * + * \return UPNP_E_SUCCESS if successful else returns appropriate error. + */ +int get_ssdp_sockets( + /* [out] Array of SSDP sockets. */ + MiniServerSockArray *out); + +/*! + * \brief This function reads the data from the ssdp socket. + */ +void readFromSSDPSocket( + /* [in] SSDP socket. */ + SOCKET socket); -/************************************************************************ -* Function : get_ssdp_sockets -* -* Parameters: -* OUT MiniServerSockArray *out: Arrays of SSDP sockets -* -* Description: -* This function creates the ssdp sockets. It set their option to listen -* for multicast traffic. -* -* Returns: int -* return UPNP_E_SUCCESS if successful else returns appropriate error -***************************************************************************/ -int get_ssdp_sockets(MiniServerSockArray *out); +/*! + * \brief This function figures out the type of the SSDP search in the in the + * request. + * + * \return enum SsdpSearchType. Returns appropriate search type, + * else returns SSDP_ERROR + */ +enum SsdpSearchType ssdp_request_type1( + /* [in] command came in the ssdp request. */ + char *cmd); -/************************************************************************ -* Function : readFromSSDPSocket -* -* Parameters: -* IN SOCKET socket: SSDP socket -* -* Description: -* This function reads the data from the ssdp socket. -* -* Returns: void -* -***************************************************************************/ -void readFromSSDPSocket(SOCKET socket); +/*! + * \brief Starts filling the SSDP event structure based upon the + * request received. + * + * \return 0 on success; -1 on error. + */ +int ssdp_request_type( + /* [in] command came in the ssdp request. */ + char *cmd, + /* [out] The event structure partially filled by this function. */ + SsdpEvent *Evt); +/*! + * \brief Creates and send the search request for a specific URL. + * + * \return 1 if successful else appropriate error. + */ +int SearchByTarget( + /* [in] Number of seconds to wait, to collect all the responses. */ + int Mx, + /* [in] Search target. */ + char *St, + /* [in] Cookie provided by control point application. This cokie will + * be returned to application in the callback. */ + void *Cookie); -/************************************************************************ -* Function : ssdp_request_type1 -* -* Parameters: -* IN char *cmd: command came in the ssdp request -* -* Description: -* This function figures out the type of the SSDP search in the -* in the request. -* -* Returns: enum SsdpSearchType -* return appropriate search type else returns SSDP_ERROR -***************************************************************************/ -enum SsdpSearchType ssdp_request_type1(IN char *cmd); - - -/************************************************************************ -* Function : ssdp_request_type -* -* Parameters: -* IN char *cmd: command came in the ssdp request -* OUT SsdpEvent *Evt: The event structure partially filled by -* this function. -* -* Description: -* This function starts filling the SSDP event structure based upon the -* request received. -* -* Returns: int -* 0 on success; -1 on error -***************************************************************************/ -int ssdp_request_type(IN char * cmd, OUT SsdpEvent * Evt); - - -/************************************************************************ -* Function : SearchByTarget -* -* Parameters: -* IN int Mx:Number of seconds to wait, to collect all the responses. -* char *St: Search target. -* void *Cookie: cookie provided by control point application. This -* cokie will be returned to application in the callback. -* -* Description: -* This function creates and send the search request for a specific URL. -* -* Returns: int -* 1 if successful else appropriate error -***************************************************************************/ -int SearchByTarget(IN int Mx, IN char *St, IN void *Cookie); - -/************************************************************************ -* Function : DeviceAdvertisement -* -* Parameters: -* IN char *DevType : type of the device -* IN int RootDev : flag to indicate if the device is root device -* IN char *Udn : -* IN char *Location: Location URL. -* IN int Duration : Service duration in sec. -* IN int AddressFamily: Device address family. -* -* Description: -* This function creates the device advertisement request based on -* the input parameter, and send it to the multicast channel. -* -* Returns: int -* UPNP_E_SUCCESS if successful else appropriate error -***************************************************************************/ +/*! + * \brief Creates the device advertisement request based on the input + * parameter, and send it to the multicast channel. + * + * \return UPNP_E_SUCCESS if successful else appropriate error. + */ int DeviceAdvertisement( - IN char *DevType, - IN int RootDev, - IN char *Udn, - IN char *Location, - IN int Duration, - IN int AddressFamily); + /* [in] type of the device. */ + char *DevType, + /* [in] flag to indicate if the device is root device. */ + int RootDev, + /* [in] UDN. */ + char *Udn, + /* [in] Location URL. */ + char *Location, + /* [in] Service duration in sec. */ + int Duration, + /* [in] Device address family. */ + int AddressFamily); - -/************************************************************************ -* Function : DeviceShutdown -* -* Parameters: -* IN char *DevType: Device Type. -* IN int RootDev:1 means root device. -* IN char *Udn: Device UDN -* IN char *_Server: -* IN char *Location: Location URL -* IN int Duration :Device duration in sec. -* IN int AddressFamily: Device address family. -* -* Description: -* This function creates a HTTP device shutdown request packet -* and sent it to the multicast channel through RequestHandler. -* -* Returns: int -* UPNP_E_SUCCESS if successful else appropriate error -***************************************************************************/ +/*! + * \brief Creates a HTTP device shutdown request packet and send it to the + * multicast channel through RequestHandler. + * + * \return UPNP_E_SUCCESS if successful else appropriate error. + */ int DeviceShutdown( - IN char *DevType, - IN int RootDev, - IN char *Udn, - IN char *_Server, - IN char *Location, - IN int Duration, - IN int AddressFamily); + /* [in] Device Type. */ + char *DevType, + /* [in] 1 means root device. */ + int RootDev, + /* [in] Device UDN. */ + char *Udn, + /* [in] . */ + char *_Server, + /* [in] Location URL. */ + char *Location, + /* [in] Device duration in sec. */ + int Duration, + /* [in] Device address family. */ + int AddressFamily); -/************************************************************************ -* Function : DeviceReply -* -* Parameters: -* IN struct sockaddr *DestAddr: destination IP address. -* IN char *DevType: Device type -* IN int RootDev: 1 means root device 0 means embedded device. -* IN char *Udn: Device UDN -* IN char *Location: Location of Device description document. -* IN int Duration :Life time of this device. -* -* Description: -* This function creates the reply packet based on the input parameter, -* and send it to the client address given in its input parameter DestAddr. -* -* Returns: int -* UPNP_E_SUCCESS if successful else appropriate error -***************************************************************************/ +/*! + * \brief Creates the reply packet based on the input parameter, and send it + * to the client address given in its input parameter DestAddr. + * + * \return UPNP_E_SUCCESS if successful else appropriate error. + */ int DeviceReply( - IN struct sockaddr *DestAddr, - IN char *DevType, - IN int RootDev, - IN char *Udn, - IN char *Location, - IN int Duration); + /* [in] destination IP address. */ + struct sockaddr *DestAddr, + /* [in] Device type. */ + char *DevType, + /* [in] 1 means root device 0 means embedded device. */ + int RootDev, + /* [in] Device UDN. */ + char *Udn, + /* [in] Location of Device description document. */ + char *Location, + /* [in] Life time of this device. */ + int Duration); -/************************************************************************ -* Function : SendReply -* -* Parameters: -* IN struct sockaddr *DestAddr: destination IP address. -* IN char *DevType: Device type -* IN int RootDev: 1 means root device 0 means embedded device. -* IN char * Udn: Device UDN -* IN char *_Server: -* IN char *Location: Location of Device description document. -* IN int Duration :Life time of this device. -* IN int ByType: -* -* Description: -* This function creates the reply packet based on the input parameter, -* and send it to the client addesss given in its input parameter DestAddr. -* -* Returns: int -* UPNP_E_SUCCESS if successful else appropriate error -***************************************************************************/ +/*! + * \brief Creates the reply packet based on the input parameter, and send it + * to the client addesss given in its input parameter DestAddr. + * + * \return UPNP_E_SUCCESS if successful else appropriate error. + */ int SendReply( - IN struct sockaddr *DestAddr, - IN char *DevType, - IN int RootDev, - IN char *Udn, - IN char *Location, - IN int Duration, - IN int ByType ); + /* [in] destination IP address. */ + struct sockaddr *DestAddr, + /* [in] Device type. */ + char *DevType, + /* [in] 1 means root device 0 means embedded device. */ + int RootDev, + /* [in] Device UDN. */ + char *Udn, + /* [in] Location of Device description document. */ + char *Location, + /* [in] Life time of this device. */ + int Duration, + /* [in] . */ + int ByType ); -/************************************************************************ -* Function : ServiceAdvertisement -* -* Parameters: -* IN char * Udn: Device UDN -* IN char *ServType: Service Type. -* IN char * Location: Location of Device description document. -* IN int Duration: Life time of this device. -* IN int AddressFamily: Device address family -* -* Description: -* This function creates the advertisement packet based -* on the input parameter, and send it to the multicast channel. -* -* Returns: int -* UPNP_E_SUCCESS if successful else appropriate error -***************************************************************************/ +/*! + * \brief Creates the advertisement packet based on the input parameter, + * and send it to the multicast channel. + * + * \return UPNP_E_SUCCESS if successful else appropriate error. + */ int ServiceAdvertisement( - IN char *Udn, - IN char *ServType, - IN char *Location, - IN int Duration, - IN int AddressFamily); + /* [in] Device UDN. */ + char *Udn, + /* [in] Service Type. */ + char *ServType, + /* [in] Location of Device description document. */ + char *Location, + /* [in] Life time of this device. */ + int Duration, + /* [in] Device address family. */ + int AddressFamily); -/************************************************************************ -* Function : ServiceReply -* -* Parameters: -* IN struct sockaddr *DestAddr: -* IN char *Udn: Device UDN -* IN char *ServType: Service Type. -* IN char *Server: Not used -* IN char *Location: Location of Device description document. -* IN int Duration :Life time of this device. -* -* Description: -* This function creates the advertisement packet based -* on the input parameter, and send it to the multicast channel. -* -* Returns: int -* UPNP_E_SUCCESS if successful else appropriate error -***************************************************************************/ +/*! + * \brief Creates the advertisement packet based on the input parameter, + * and send it to the multicast channel. + * + * \return UPNP_E_SUCCESS if successful else appropriate error. + */ int ServiceReply( - IN struct sockaddr *DestAddr, - IN char *ServType, - IN char *Udn, - IN char *Location, - IN int Duration); + /* [in] . */ + struct sockaddr *DestAddr, + /* [in] Service Type. */ + char *ServType, + /* [in] Device UDN. */ + char *Udn, + /* [in] Location of Device description document. */ + char *Location, + /* [in] Life time of this device. */ + int Duration); -/************************************************************************ -* Function : ServiceShutdown -* -* Parameters: -* IN char *Udn: Device UDN -* IN char *ServType: Service Type. -* IN char *Location: Location of Device description document. -* IN int Duration :Service duration in sec. -* IN int AddressFamily: Device address family -* -* Description: -* This function creates a HTTP service shutdown request packet -* and sent it to the multicast channel through RequestHandler. -* -* Returns: int -* UPNP_E_SUCCESS if successful else appropriate error -***************************************************************************/ +/*! + * \brief Creates a HTTP service shutdown request packet and sends it to the + * multicast channel through RequestHandler. + * + * \return UPNP_E_SUCCESS if successful else appropriate error. + */ int ServiceShutdown( - IN char *Udn, - IN char *ServType, - IN char *Location, - IN int Duration, - IN int AddressFamily); + /* [in] Device UDN. */ + char *Udn, + /* [in] Service Type. */ + char *ServType, + /* [in] Location of Device description document. */ + char *Location, + /* [in] Service duration in sec. */ + int Duration, + /* [in] Device address family. */ + int AddressFamily); +/*! + * \brief Wrapper function to reply the search request coming from the + * control point. + * + * \return always return NULL + */ +void *advertiseAndReplyThread( + /* [in] Structure containing the search request. */ + void *data); -/************************************************************************ -* Function : advertiseAndReplyThread -* -* Parameters: -* IN void *data: Structure containing the search request -* -* Description: -* This function is a wrapper function to reply the search request -* coming from the control point. -* -* Returns: void * -* always return NULL -***************************************************************************/ -void *advertiseAndReplyThread(IN void * data); - -/************************************************************************ -* Function : AdvertiseAndReply -* -* Parameters: -* IN int AdFlag: -1 = Send shutdown, -* 0 = send reply, -* 1 = Send Advertisement -* IN UpnpDevice_Handle Hnd: Device handle -* IN enum SsdpSearchType SearchType:Search type for sending replies -* IN struct sockaddr *DestAddr:Destination address -* IN char *DeviceType:Device type -* IN char *DeviceUDN:Device UDN -* IN char *ServiceType:Service type -* IN int Exp:Advertisement age -* -* Description: -* This function to send SSDP advertisements, replies and shutdown messages. -* -* Returns: int -* UPNP_E_SUCCESS if successful else appropriate error -***************************************************************************/ +/*! + * \brief Sends SSDP advertisements, replies and shutdown messages. + * + * \return UPNP_E_SUCCESS if successful else appropriate error. + */ int AdvertiseAndReply( - IN int AdFlag, - IN UpnpDevice_Handle Hnd, - IN enum SsdpSearchType SearchType, - IN struct sockaddr *DestAddr, - IN char *DeviceType, - IN char *DeviceUDN, - IN char *ServiceType, int Exp); + /* [in] -1 = Send shutdown, 0 = send reply, 1 = Send Advertisement. */ + int AdFlag, + /* [in] Device handle. */ + UpnpDevice_Handle Hnd, + /* [in] Search type for sending replies. */ + enum SsdpSearchType SearchType, + /* [in] Destination address. */ + struct sockaddr *DestAddr, + /* [in] Device type. */ + char *DeviceType, + /* [in] Device UDN. */ + char *DeviceUDN, + /* [in] Service type. */ + char *ServiceType, + /* [in] Advertisement age. */ + int Exp); #endif /* SSDPLIB_H */ -