upnp.h

原来由英特尔制定的UPnP SDK的

                            unregister. */
   );


/** OBSOLETE METHOD : use {\bf UpnpSetMaxContentLength} instead.
 * Warning: the Handle argument provided here is not used, so the effect
 * of this function is global to the SDK (= same as 
 * {\bf UpnpSetMaxContentLength} ).
 */
EXPORT_SPEC int UpnpSetContentLength(
    IN UpnpClient_Handle Hnd,  
    IN int contentLength       
    );


/** Sets the maximum content-length that the SDK will process on an incoming 
 *  SOAP requests or responses. This API allows devices that have memory 
 *  constraints to exhibit consistent behaviour if the size of the 
 *  incoming SOAP message exceeds the memory that device can allocate. 
 *  The default maximum content-length is {\tt DEFAULT_SOAP_CONTENT_LENGTH} 
 *  = 16K bytes.
 *   
 *  @return [int] An integer representing one of the following:
 *    \begin{itemize}
 *      \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
 *    \end{itemize}
 */
EXPORT_SPEC int UpnpSetMaxContentLength(
    IN size_t contentLength    /** The maximum permissible content length 
			           for incoming SOAP actions, in bytes. */
    );

/*! @} */ /* 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
 *  instance issued a particular search.  Therefore, the client can get
 *  search callbacks that do not match the original criteria of the search.
 *  Also, the application will receive multiple callbacks for each search.
 *
 *  @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.
 *      \item {\tt UPNP_E_INVALID_PARAM}: {\bf Target} is {\tt NULL}.
 *    \end{itemize} */

EXPORT_SPEC int UpnpSearchAsync(
    IN UpnpClient_Handle Hnd, /** The handle of the client performing 
                                  the search. */
    IN int Mx,                /** The time, in seconds, to wait for 
                                  responses. If the time is greater 
                                  than {\tt MAX_SEARCH_TIME} then the time is 
                                  set to {\tt MAX_SEARCH_TIME}. If the time is 
                                  less than {\tt MIN_SEARCH_TIME} then the 
                                  time is set to {\tt MIN_SEARCH_TIME}. */ 
    IN const char *Target,    /** The search target as defined in the UPnP 
                                  Device Architecture v1.0 specification. */
    IN const void *Cookie     /** The user data to pass when the callback 
                                  function is invoked. */
    ); 

/** {\bf UpnpSendAdvertisement} sends out the discovery announcements for
 *  all devices and services for a device.  Each announcement is made with
 *  the same expiration time.
 *
 *  {\bf UpnpSendAdvertisement} is a synchronous call.
 *
 *  @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_OUTOF_MEMORY}: There are insufficient resources to 
 *              send future advertisements.
 *    \end{itemize}
 */
EXPORT_SPEC int UpnpSendAdvertisement(
    IN UpnpDevice_Handle Hnd, /** The device handle for which to send out the 
                                  announcements. */
    IN int Exp                /** The expiration age, in seconds, of 
                                  the announcements. */
    );

/*! @} */ /* Discovery */

/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                            C O N T R O L                                   *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/

/*! @name Control */
/*! @{ */

/** {\bf UpnpGetServiceVarStatus} queries the state of a state 
 *  variable of a service on another device.  This is a synchronous call.
 *  A positive return value indicates a SOAP error code, whereas a negative
 *  return code indicates an SDK error code. {\bf Note that the use of this 
 *  function is deprecated by the UPnP Forum}.
 *
 *  @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.
 *      \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL.
 *      \item {\tt UPNP_E_INVALID_DESC}: The XML document was not 
 *              found or it does not contain a valid XML description.
 *      \item {\tt UPNP_E_INVALID_PARAM}: {\bf StVarVal} is not a valid 
 *              pointer or {\bf VarName} or {\bf ActionUrl} is {\tt NULL}. 
 *      \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to 
 *              complete this operation.
 *      \item {\tt UPNP_SOAP_E_INVALID_VAR}: The given variable is invalid 
 *              according to the device.
 *    \end{itemize}
 */

EXPORT_SPEC int UpnpGetServiceVarStatus(
    IN UpnpClient_Handle Hnd,     /** The handle of the control point. */
    IN const char *ActionURL,     /** The URL of the service. */
    IN const char *VarName,       /** The name of the variable to query. */
    OUT DOMString *StVarVal       /** The pointer to store the value 
                                      for {\bf VarName}. The SDK 
                                      allocates this string and the caller 
                                      needs to free it using 
				      {\bf ixmlFreeDOMString}. */
    );

/** {\bf UpnpGetServiceVarStatusAsync} queries the state of a variable of a 
 *  service, generating a callback when the operation is complete. {\bf Note 
 *  that the use of this function is deprecated by the UPnP Forum}.
 *
 *  @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.
 *      \item {\tt UPNP_E_INVALID_URL}: The {\bf ActionUrl} is not a valid URL.
 *      \item {\tt UPNP_E_INVALID_PARAM}: {\bf VarName}, {\bf Fun} or 
 *              {\bf ActionUrl} is not a valid pointer.
 *      \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to 
 *              complete this operation.
 *    \end{itemize}
 */

EXPORT_SPEC int UpnpGetServiceVarStatusAsync(
    IN UpnpClient_Handle Hnd, /** The handle of the control point. */
    IN const char *ActionURL, /** The URL of the service. */
    IN const char *VarName,   /** The name of the variable to query. */
    IN Upnp_FunPtr Fun,       /** Pointer to a callback function to 
                                  be invoked when the operation is complete. */
    IN const void *Cookie     /** Pointer to user data to pass to the 
                                  callback function when invoked. */
    );

/** {\bf UpnpSendAction} sends a message to change a state variable
 *  in a service.  This is a synchronous call that does not return until the 
 *  action is complete.
 * 
 *  Note that a positive return value indicates a SOAP-protocol error code.
 *  In this case,  the error description can be retrieved from {\bf RespNode}.
 *  A negative return value indicates an SDK 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 control 
 *              point handle.
 *      \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL.
 *      \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid.
 *      \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is not a 
 *              valid device.
 *      \item {\tt UPNP_E_INVALID_PARAM}: {\bf ServiceType}, {\bf Action}, 
 *              {\bf ActionUrl}, or 
 *              {\bf RespNode} is not a valid pointer.
 *      \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to 
 *              complete this operation.
 *    \end{itemize}
 */

EXPORT_SPEC int UpnpSendAction(
    IN UpnpClient_Handle Hnd,     /** The handle of the control point 
                                      sending the action. */
    IN const char *ActionURL,     /** The action URL of the service. */
    IN const char *ServiceType,   /** The type of the service. */
    IN const char *DevUDN,        /** This parameter is ignored and must be
				      {\tt NULL}. */
    IN IXML_Document *Action,     /** The DOM document for the action. */
    OUT IXML_Document **RespNode  /** The DOM document for the response 
                                    to the action.  The SDK allocates 
                                    this document and the caller needs to free 
                                    it.  */
   );

/** {\bf UpnpSendActionEx} sends a message to change a state variable
 *  in a service.  This is a synchronous call that does not return until the 
 *  action is complete.
 *
 *  Note that a positive return value indicates a SOAP-protocol error code.
 *  In this case,  the error description can be retrieved from {\bf RespNode}.
 *  A negative return value indicates an SDK 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 control 
 *              point handle.
 *      \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL.
 *      \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid.
 *      \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is not a 
 *              valid device.
 *      \item {\tt UPNP_E_INVALID_PARAM}: {\bf ServiceType}, {\bf Action}, 
 *              {\bf ActionUrl}, or 
 *              {\bf RespNode} is not a valid pointer.
 *      \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to 
 *              complete this operation.
 *    \end{itemize}
 */

EXPORT_SPEC int UpnpSendActionEx(
    IN UpnpClient_Handle Hnd,    /** The handle of the control point 
                                     sending the action. */
    IN const char *ActionURL,    /** The action URL of the service. */
    IN const char *ServiceType,  /** The type of the service. */
    IN const char *DevUDN,       /** This parameter is ignored and must be
				     {\tt NULL}. */
    IN IXML_Document *Header,    /** The DOM document for the SOAP header. 
                                     This may be {\tt NULL} if the header is 
				     not required. */
    IN IXML_Document *Action,    /** The DOM document for the action. */
    OUT IXML_Document **RespNode /** The DOM document for the response 
                                     to the action.  The SDK allocates 
                                     this document and the caller needs to free 
                                     it.  */
   );

/** {\bf UpnpSendActionAsync} sends a message to change a state variable
 *  in a service, generating a callback when the operation is complete.
 *  See {\bf UpnpSendAction} for comments on positive return values. These 
 *  positive return values are sent in the event struct associated with the
 *  {\tt UPNP_CONTROL_ACTION_COMPLETE} event.
 *
 *  @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.
 *      \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is an invalid URL.
 *      \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is an invalid device.
 *      \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Fun} is not a valid 
 *              callback function or {\bf ServiceType}, {\bf Act}, or 
 *              {\bf ActionUrl} is {\tt NULL}.
 *      \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid.
 *      \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to 
 *              complete this operation.
 *    \end{itemize}
 */

EXPORT_SPEC int UpnpSendActionAsync(
    IN UpnpClient_Handle Hnd,   /** The handle of the control point 
                                    sending the action. */
    IN const char *ActionURL,   /** The action URL of the service. */
    IN const char *ServiceType, /** The type of the service. */
    IN const char *DevUDN,      /** This parameter is ignored and must be
				    {\tt NULL}. */
    IN IXML_Document *Action,   /** The DOM document for the action to 
                                    perform on this device. */
    IN Upnp_FunPtr Fun,         /** Pointer to a callback function to 
                                    be invoked when the operation 
		                    completes. */
    IN const void *Cookie       /** Pointer to user data that to be 
                                    passed to the callback when invoked. */
    );

/** {\bf UpnpSendActionExAsync} sends a message to change a state variable
 *  in a service, generating a callback when the operation is complete.
 *  See {\bf UpnpSendAction} for comments on positive return values. These 
 *  positive return values are sent in the event struct associated with the
 *  {\tt UPNP_CONTROL_ACTION_COMPLETE} event.
 *
 *  @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.
 *      \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is an invalid URL.
 *      \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is an invalid device.
 *      \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Fun} is not a valid 
 *              callback function or {\bf ServiceType}, {\bf Act}, or 
 *              {\bf ActionUrl} is {\tt NULL}.
 *      \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid.
 *      \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to 
 *              complete this operation.
 *    \end{itemize}
 */

EXPORT_SPEC int UpnpSendActionExAsync(
    IN UpnpClient_Handle Hnd,   /** The handle of the control point 
                                    sending the action. */
    IN const char *ActionURL,   /** The action URL of the service. */
    IN const char *ServiceType, /** The type of the service. */
    IN const char *DevUDN,      /** This parameter is ignored and must be
				    {\tt NULL}. */
    IN IXML_Document *Header,   /** The DOM document for the SOAP header. 
                                    This may be {\tt NULL} if the header is 
				    not required. */
    IN IXML_Document *Action,   /** The DOM document for the action to 
                                    perform on this device. */
    IN Upnp_FunPtr Fun,         /** Pointer to a callback function to 
                                    be invoked when the operation 
				    completes. */
    IN const void *Cookie       /** Pointer to user data that to be 
                                    passed to the callback when invoked. */
    );

/*! @} */ /* Control */

/******