upnp.h

电驴下载工具eMule0.47aVeryCD的源代码,可作分析测试也可用于P2P软件的开发研究.

                                        that this must be positive if the 
                                        {\bf origin} is {\tt SEEK_SET}. */
     IN int origin                  /** The position to move relative to.  It 
                                        can be {\tt SEEK_CUR} to move relative 
                                        to the current position, 
					{\tt SEEK_END} to move relative to 
					the end of the file, or {\tt 
					SEEK_SET} to specify an absolute 
					offset. */
     );

   /** Called by the web server to close a file opened via the {\bf open}
    *  callback.  It should return 0 on success, or a non-zero value on an 
    *  error.
    */
   int (*close) (
     IN UpnpWebFileHandle fileHnd   /** The handle of the file to close. */
     );

};

typedef struct virtual_Dir_List
{
    struct virtual_Dir_List *next;
    char dirName[UPNP_NAME_SIZE];
} virtualDirList;

/** All callback functions share the same prototype, documented below.
 *  Note that any memory passed to the callback function
 *  is valid only during the callback and should be copied if it
 *  needs to persist.  This callback function needs to be thread
 *  safe.  The context of the callback is always on a valid thread 
 *  context and standard synchronization methods can be used.  Note, 
 *  however, because of this the callback cannot call SDK functions
 *  unless explicitly noted.
 *
 *  \begin{verbatim}
      int CallbackFxn( Upnp_EventType EventType, void* Event, void* Cookie );
    \end{verbatim} 
 *
 *  where {\bf EventType} is the event that triggered the callback, 
 *  {\bf Event} is a structure that denotes event-specific information for that
 *  event, and {\bf Cookie} is the user data passed when the callback was
 *  registered.
 *
 *  See {\bf Upnp_EventType} for more information on the callback values and
 *  the associated {\bf Event} parameter.  
 *
 *  The return value of the callback is currently ignored.  It may be used
 *  in the future to communicate results back to the SDK.
 */

typedef int  (*Upnp_FunPtr) (
    IN Upnp_EventType EventType, 
    IN void *Event, 
    IN void *Cookie
    );

//@} // Constants, Structures, and Types

#ifdef __cplusplus
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} */

EXPORT_SPEC 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} */

EXPORT_SPEC 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. 
 */
EXPORT_SPEC 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. 
 */
EXPORT_SPEC 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}
 */

EXPORT_SPEC 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} */

EXPORT_SPEC 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} */
 
EXPORT_SPEC 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} */

EXPORT_SPEC 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