extern "C" {#endif // __cplusplus///@name Initialization and Registration//@{/** Initializes the Linux SDK for UPnP Devices. This function must be called *  before any other API function can be called.  It should be called *  only once.  Subsequent calls to this API return a {\tt UPNP_E_INIT} *  error code. * *  Optionally, the application can specify a host IP address (in the *  case of a multi-homed configuration) and a port number to use for *  all UPnP operations.  Since a port number can be used only by one *  process, multiple processes using the SDK must specify *  different port numbers. * *  If unspecified, the SDK will use the first adapter's IP address  *  and an arbitrary port. * *  This call is synchronous. * *  @return [int] An integer representing one of the following: *    \begin{itemize} *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. *      \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist  *              to initialize the SDK. *      \item {\tt UPNP_E_INIT}: The SDK is already initialized.  *      \item {\tt UPNP_E_INIT_FAILED}: The SDK initialization  *              failed for an unknown reason. *      \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. *      \item {\tt UPNP_E_LISTEN}: An error occurred listening to a socket. *      \item {\tt UPNP_E_OUTOF_SOCKET}: An error ocurred creating a socket. *      \item {\tt UPNP_E_INTERNAL_ERROR}: An internal error ocurred. *    \end{itemize} */int UpnpInit(    IN const char *HostIP,      /** The host IP address to use, in                                     string format, for example "192.168.0.1",                                     or {\tt NULL} to use the first adapter's                                     IP address. */    IN unsigned short DestPort  /** The destination port number to use.  0                                     will pick an arbitrary free port. */    );/** Terminates the Linux SDK for UPnP Devices. This function must be the last  *  API function called. It should be called only once. Subsequent calls to  *  this API return a {\tt UPNP_E_FINISH} error code. * *  @return [int] An integer representing one of the following: *    \begin{itemize} *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. *      \item {\tt UPNP_E_FINISH}: The SDK is already terminated or  *                                 it is not initialized.  *    \end{itemize} */int UpnpFinish();/** If '0' is used as the port number in {\bf UpnpInit}, then this *  function can be used to retrieve the actual port allocated to *  the SDK. If {\bf UpnpInit} has not succeeded then 0 is  *  returned. * *  @return [unsigned short] The port on which an internal server is  *                           listening for UPnP related requests.  */unsigned short UpnpGetServerPort(void);/** If {\tt NULL} is used as the IP address in {\bf UpnpInit}, then this *  function can be used to retrieve the actual interface address *  on which device is running. If {\bf UpnpInit} has not succeeded  *  then {\tt NULL} is returned. * *  @return [char*] The IP address on which an internal server is listening  *                  for UPnP related requests.  */char * UpnpGetServerIpAddress(void);/** {\bf UpnpRegisterClient} registers a control point application with the *  SDK.  A control point application cannot make any other API calls *  until it registers using this function. * *  {\bf UpnpRegisterClient} is a synchronous call and generates no callbacks. *  Callbacks can occur as soon as this function returns. * *  @return [int] An integer representing one of the following: *    \begin{itemize} *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. *      \item {\tt UPNP_E_FINISH}: The SDK is already terminated or  *                                 is not initialized.  *      \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd}  *              is not a valid pointer. *      \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to  *              register this control point. *    \end{itemize} */int UpnpRegisterClient(    IN Upnp_FunPtr Callback,   /** Pointer to a function for receiving                                    asynchronous events. */    IN const void *Cookie,     /** Pointer to user data returned with the                                    callback function when invoked. */    OUT UpnpClient_Handle *Hnd /** Pointer to a variable to store the                                    new control point handle. */    );  /** {\bf UpnpRegisterRootDevice} registers a device application with *  the SDK.  A device application cannot make any other API *  calls until it registers using this function.  Device applications *  can also register as control points (see {\bf UpnpRegisterClient} *  to get a control point handle to perform control point *  functionality). * *  {\bf UpnpRegisterRootDevice} is synchronous and does not generate *  any callbacks.  Callbacks can occur as soon as this function returns. * *  @return [int] An integer representing one of the following: *    \begin{itemize} *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. *      \item {\tt UPNP_E_FINISH}: The SDK is already terminated or  *                                 is not initialized.  *      \item {\tt UPNP_E_INVALID_DESC}: The description document was not  *              a valid device description. *      \item {\tt UPNP_E_INVALID_URL}: The URL for the description document  *              is not valid. *      \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd}  *              is not a valid pointer or {\bf DescURL} is {\tt NULL}. *      \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. *      \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing  *              to a socket. *      \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading  *              from a socket. *      \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. *      \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting the  *              socket. *      \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently  *              allocated. *      \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to  *              register this root device. *    \end{itemize} */int UpnpRegisterRootDevice(    IN const char *DescUrl,    /** Pointer to a string containing the                                    description URL for this root device                                    instance. */    IN Upnp_FunPtr Callback,   /** Pointer to the callback function for                                    receiving asynchronous events. */    IN const void *Cookie,     /** Pointer to user data returned with the                                    callback function when invoked. */    OUT UpnpDevice_Handle *Hnd /** Pointer to a variable to store the                                    new device handle. */    );/** {\bf UpnpRegisterRootDevice2} is similar to {\bf UpnpRegisterRootDevice}, *  except that it also allows the description document to be specified as a  *  file or a memory buffer. The description can also be configured to have the *  correct IP and port address. * *  NOTE: For the configuration to be functional, the internal web server *  MUST be present. In addition, the web server MUST be activated *  (using {\bf UpnpSetWebServerRootDir}) before calling this function. *  The only condition where the web server can be absent is if the  *  description document is specified as a URL and no configuration is  *  required (i.e. {\tt config_baseURL = 0}.) * *  {\bf UpnpRegisterRootDevice2} is synchronous and does not generate *  any callbacks.  Callbacks can occur as soon as this function returns. * *  Examples of using different types of description documents: *  \begin{verbatim}    1) Description specified as a URL:          descriptionType == UPNPREG_URL_DESC          description is the URL          bufferLen = 0 (ignored)    2) Description specified as a file:          descriptionType == UPNPREG_FILENAME_DESC          description is a filename          bufferLen = 0 (ignored)    3) Description specified as a memory buffer:          descriptionType == UPNPREG_BUF_DESC          description is pointer to a memory buffer          bufferLen == length of memory buffer    \end{verbatim} * *  @return [int] An integer representing one of the following: *    \begin{itemize} *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. *      \item {\tt UPNP_E_FINISH}: The SDK is already terminated or  *                                 is not initialized. *      \item {\tt UPNP_E_INVALID_DESC}: The description document is not  *              a valid device description. *      \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd}  *              is not a valid pointer or {\bf DescURL} is {\tt NULL}. *      \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred. *      \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing  *              to a socket. *      \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading  *              from a socket. *      \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket. *      \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting the  *              socket. *      \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently  *              allocated. *      \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to  *              register this root device. *      \item {\tt UPNP_E_URL_TOO_BIG}: Length of the URL is bigger than the  *              internal buffer. *      \item {\tt UPNP_E_FILE_NOT_FOUND}: The description file could not  *              be found. *      \item {\tt UPNP_E_FILE_READ_ERROR}: An error occurred reading the  *              description file. *      \item {\tt UPNP_E_INVALID_URL}: The URL to the description document  *              is invalid. *      \item {\tt UPNP_E_EXT_NOT_XML}: The URL to the description document  *              or file should have a {\tt .xml} extension. *      \item {\tt UPNP_E_NO_WEB_SERVER}: The internal web server has been  *              compiled out; the SDK cannot configure itself from the  *              description document. *    \end{itemize} */ int UpnpRegisterRootDevice2(    IN Upnp_DescType descriptionType,/** The type of the description                                          document. */    IN const char* description,      /** Treated as a URL, file name or                                          memory buffer depending on                                          description type. */    IN size_t bufferLen,             /** The length of memory buffer if                                          passing a description in a buffer,                                          otherwise it is ignored. */    IN int config_baseURL,           /** If nonzero, {\tt URLBase} of                                          description document is                                          configured and the description                                          is served using the internal                                          web server. */    IN Upnp_FunPtr Fun,              /** Pointer to the callback function                                          for receiving asynchronous                                          events. */    IN const void* Cookie,           /** Pointer to user data returned                                          with the callback function when                                          invoked. */    OUT UpnpDevice_Handle* Hnd       /** Pointer to a variable to store                                          the new device handle. */    );/** {\bf UpnpUnRegisterClient} unregisters a control point application,  *  unsubscribing all active subscriptions. After this call, the  *  {\bf UpnpClient_Handle} is no longer valid. * *  {\bf UpnpUnRegisterClient} is a synchronous call and generates no *  callbacks.  The SDK generates no more callbacks after this  *  function returns. * *  @return [int] An integer representing one of the following: *    \begin{itemize} *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. *      \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control  *                   point handle. *    \end{itemize} */int UpnpUnRegisterClient(    IN UpnpClient_Handle Hnd  /** The handle of the control point instance                                   to unregister. */    );/** Unregisters a root device registered with {\bf UpnpRegisterRootDevice} or *  {\bf UpnpRegisterRootDevice2}. After this call, the  *  {\bf UpnpDevice_Handle} is no longer valid. For all advertisements that  *  have not yet expired, the SDK sends a device unavailable message  *  automatically. * *  {\bf UpnpUnRegisterRootDevice} is a synchronous call and generates no *  callbacks.  Once this call returns, the SDK will no longer  *  generate callbacks to the application. * *  @return [int] An integer representing one of the following: *    \begin{itemize} *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. *      \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid   *              device handle. *    \end{itemize} */int UpnpUnRegisterRootDevice(   IN UpnpDevice_Handle /** The handle of the root device instance to                             unregister. */   );/** Sets the size of the receive buffer for incoming SOAP requests. This API  *  allows devices that have memory constraints to exhibit consistent  *  behaviour if the size of the incoming SOAP request exceeds the memory  *  that device can allocate for incoming SOAP messages. The default  *  value set by the SDK for the buffer is 16K bytes.  Trying to set a value  *  greater than 32K will result in an error. *    *  @return [int] An integer representing one of the following: *    \begin{itemize} *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully. *      \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid  *              device handle. *      \item {\tt UPNP_E_LARGE_BUFFER_SIZE}: The buffer size requested was  *              too large. *    \end{itemize} */int UpnpSetContentLength(    IN UpnpClient_Handle Hnd,  /** The handle of the device instance                                    for which the coincoming content length 				   needs to be set. */    IN int contentLength       /** The maximum permissible content length 			           for incoming SOAP actions. */    );//@} // Initialization and Registration//////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////                                                                    ////                        D I S C O V E R Y                           ////                                                                    /////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////@name Discovery//@{/** {\bf UpnpSearchAsync} searches for devices matching the given *  search target.  The function returns immediately and the SDK  *  calls the default callback function, registered during the  *  {\bf UpnpRegisterClient} call, for each matching root device, *  device, or service.  The application specifies the search type by the  *  {\bf Target} parameter.   * *  Note that there is no way for the SDK to distinguish which client