upnp.h

Go to the documentation of this file.

#ifndef UPNP_H
#define UPNP_H
 
/*******************************************************************************
 *
 * Copyright (c) 2000-2003 Intel Corporation
 * All rights reserved.
 * Copyright (C) 2011-2012 France Telecom All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * * Redistributions of source code must retain the above copyright notice,
 * this list of conditions and the following disclaimer.
 * * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 * * Neither name of Intel Corporation nor the names of its contributors
 * may be used to endorse or promote products derived from this software
 * without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 ******************************************************************************/

 
#include "UpnpGlobal.h"
#include "UpnpInet.h" /* IWYU pragma: keep */
#include "ixml.h"
#include "upnpconfig.h" /* IWYU pragma: keep */
 
/*
 * \todo Document the exact reason of these include files and solve this
 * include mess in an include file like UpnpTime.h
 */
#ifdef _WIN32
        #include <time.h>
        #if defined(UPNP_USE_MSVCPP) || defined(UPNP_USE_BCBPP)
                #include <sys/types.h> /* needed for off_t */
        #endif
#elif (defined(BSD) && BSD >= 199306)
        #include <time.h>
#else
        /* Other systems ??? */
#endif
 
#ifdef UPNP_ENABLE_OPEN_SSL
        #include <openssl/ssl.h>
#endif
 
#define LINE_SIZE (size_t)180
#define NAME_SIZE (size_t)256
#define MNFT_NAME_SIZE 64
#define MODL_NAME_SIZE 32
#define SERL_NUMR_SIZE 64
#define MODL_DESC_SIZE 64
#define UPNP_INFINITE -1
#define UPNP_USING_CHUNKED -3
#define UPNP_UNTIL_CLOSE -4


#define UPNP_E_SUCCESS 0

#define UPNP_E_INVALID_HANDLE -100

#define UPNP_E_INVALID_PARAM -101

#define UPNP_E_OUTOF_HANDLE -102
 
#define UPNP_E_OUTOF_CONTEXT -103

#define UPNP_E_OUTOF_MEMORY -104

#define UPNP_E_INIT -105
 
#define UPNP_E_BUFFER_TOO_SMALL -106

#define UPNP_E_INVALID_DESC -107

#define UPNP_E_INVALID_URL -108
 
#define UPNP_E_INVALID_SID -109
 
#define UPNP_E_INVALID_DEVICE -110

#define UPNP_E_INVALID_SERVICE -111

#define UPNP_E_BAD_RESPONSE -113
 
#define UPNP_E_BAD_REQUEST -114

#define UPNP_E_INVALID_ACTION -115

#define UPNP_E_FINISH -116

#define UPNP_E_INIT_FAILED -117

#define UPNP_E_URL_TOO_BIG -118

#define UPNP_E_BAD_HTTPMSG -119

#define UPNP_E_ALREADY_REGISTERED -120

#define UPNP_E_INVALID_INTERFACE -121

#define UPNP_E_NETWORK_ERROR -200

#define UPNP_E_SOCKET_WRITE -201

#define UPNP_E_SOCKET_READ -202

#define UPNP_E_SOCKET_BIND -203

#define UPNP_E_SOCKET_CONNECT -204

#define UPNP_E_OUTOF_SOCKET -205

#define UPNP_E_LISTEN -206

#define UPNP_E_TIMEDOUT -207

#define UPNP_E_SOCKET_ERROR -208
 
#define UPNP_E_FILE_WRITE_ERROR -209

#define UPNP_E_CANCELED -210
 
#define UPNP_E_EVENT_PROTOCOL -300

#define UPNP_E_SUBSCRIBE_UNACCEPTED -301

#define UPNP_E_UNSUBSCRIBE_UNACCEPTED -302

#define UPNP_E_NOTIFY_UNACCEPTED -303

#define UPNP_E_INVALID_ARGUMENT -501

#define UPNP_E_FILE_NOT_FOUND -502

#define UPNP_E_FILE_READ_ERROR -503

#define UPNP_E_EXT_NOT_XML -504
 
#define UPNP_E_NO_WEB_SERVER -505
#define UPNP_E_OUTOF_BOUNDS -506

#define UPNP_E_NOT_FOUND -507

#define UPNP_E_INTERNAL_ERROR -911
 
/* SOAP-related error codes */
#define UPNP_SOAP_E_INVALID_ACTION 401
#define UPNP_SOAP_E_INVALID_ARGS 402
#define UPNP_SOAP_E_OUT_OF_SYNC 403
#define UPNP_SOAP_E_INVALID_VAR 404
#define UPNP_SOAP_E_ACTION_FAILED 501
 
/* @} ErrorCodes */
 
/*
 * Opaque data structures. The following includes are data structures that
 * must be externally visible. Since version 1.8.0, only an opaque typedef
 * is visible from the outside world. Any operation on these data types
 * must be done using the appropriate interface functions.
 *
 * This policy has the great advantage that it is now possible to change
 * the internal implementation of these data structures without breaking
 * the API.
 */
#include "UpnpActionComplete.h"      // IWYU pragma: keep
#include "UpnpActionRequest.h"       // IWYU pragma: keep
#include "UpnpDiscovery.h"           // IWYU pragma: keep
#include "UpnpEvent.h"               // IWYU pragma: keep
#include "UpnpEventSubscribe.h"      // IWYU pragma: keep
#include "UpnpFileInfo.h"            // IWYU pragma: keep
#include "UpnpStateVarComplete.h"    // IWYU pragma: keep
#include "UpnpStateVarRequest.h"     // IWYU pragma: keep
#include "UpnpSubscriptionRequest.h" // IWYU pragma: keep

 
enum UpnpOpenFileMode
{
        UPNP_READ,
        UPNP_WRITE
};

typedef int UpnpClient_Handle;

typedef int UpnpDevice_Handle;

typedef char Upnp_SID[44];

enum Upnp_SType_e
{
        UPNP_S_ALL,

        UPNP_S_ROOT,

        UPNP_S_DEVICE,

        UPNP_S_SERVICE
};
 
typedef enum Upnp_SType_e Upnp_SType;

enum Upnp_DescType_e
{
        UPNPREG_URL_DESC,

        UPNPREG_FILENAME_DESC,

        UPNPREG_BUF_DESC
};
 
typedef enum Upnp_DescType_e Upnp_DescType;
 
#include "Callback.h"
 
/* @} Constants and Types */
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */


UPNP_EXPORT_SPEC int UpnpInit2(
        const char *IfName,
        unsigned short DestPort);

#ifdef UPNP_ENABLE_OPEN_SSL
UPNP_EXPORT_SPEC int UpnpInitSslContext(
        int initOpenSslLib,
        const SSL_METHOD *sslMethod);

UPNP_EXPORT_SPEC SSL_CTX *UpnpGetSslCtx(void);

UPNP_EXPORT_SPEC int UpnpSetSslCtx(
        SSL_CTX *ctx);
#endif

UPNP_EXPORT_SPEC int UpnpFinish(void);

UPNP_EXPORT_SPEC unsigned short UpnpGetServerPort(void);

UPNP_EXPORT_SPEC unsigned short UpnpGetServerPort6(void);

UPNP_EXPORT_SPEC unsigned short UpnpGetServerUlaGuaPort6(void);

UPNP_EXPORT_SPEC unsigned short UpnpGetSsdpReqPort4(void);

UPNP_EXPORT_SPEC unsigned short UpnpGetSsdpReqPort6(void);

UPNP_EXPORT_SPEC char *UpnpGetServerIpAddress(void);

UPNP_EXPORT_SPEC char *UpnpGetServerIp6Address(void);

UPNP_EXPORT_SPEC char *UpnpGetServerUlaGuaIp6Address(void);
UPNP_EXPORT_SPEC int UpnpRegisterRootDevice(
        const char *DescUrl,
        Upnp_FunPtr Callback,
        const void *Cookie,
        UpnpDevice_Handle *Hnd);

UPNP_EXPORT_SPEC int UpnpRegisterRootDevice2(
        Upnp_DescType descriptionType,
        const char *description,
        size_t bufferLen,
        int config_baseURL,
        Upnp_FunPtr Fun,
        const void *Cookie,
        UpnpDevice_Handle *Hnd);

UPNP_EXPORT_SPEC int UpnpRegisterRootDevice3(
        const char *DescUrl,
        Upnp_FunPtr Callback,
        const void *Cookie,
        UpnpDevice_Handle *Hnd,
        int AddressFamily);

UPNP_EXPORT_SPEC int UpnpRegisterRootDevice4(
        const char *DescUrl,
        Upnp_FunPtr Callback,
        const void *Cookie,
        UpnpDevice_Handle *Hnd,
        int AddressFamily,
        const char *LowerDescUrl);

UPNP_EXPORT_SPEC int UpnpUnRegisterRootDevice(
        UpnpDevice_Handle Hnd);

UPNP_EXPORT_SPEC int UpnpUnRegisterRootDeviceLowPower(
        UpnpDevice_Handle Hnd,
        int PowerState,
        int SleepPeriod,
        int RegistrationState);

UPNP_EXPORT_SPEC int UpnpRegisterClient(
        Upnp_FunPtr Callback,
        const void *Cookie,
        UpnpClient_Handle *Hnd);

UPNP_EXPORT_SPEC int UpnpUnRegisterClient(
        UpnpClient_Handle Hnd);

UPNP_EXPORT_SPEC int UpnpSetMaxContentLength(
        size_t contentLength);

UPNP_EXPORT_SPEC int UpnpSetMaxHeaderSize(
        size_t headerSize);
 
/* @} Initialization and Registration */
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                        D I S C O V E R Y                                   *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/


UPNP_EXPORT_SPEC int UpnpSearchAsync(
        UpnpClient_Handle Hnd,
        int Mx,
        const char *Target_const,
        const void *Cookie_const);

UPNP_EXPORT_SPEC int UpnpSendAdvertisement(
        UpnpDevice_Handle Hnd,
        int Exp);

UPNP_EXPORT_SPEC int UpnpSendAdvertisementLowPower(
        UpnpDevice_Handle Hnd,
        int Exp,
        int PowerState,
        int SleepPeriod,
        int RegistrationState);
 
/* @} Discovery */
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                            C O N T R O L                                   *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/


UPNP_EXPORT_SPEC int UpnpGetServiceVarStatus(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *VarName,
        DOMString *StVarVal);

UPNP_EXPORT_SPEC int UpnpGetServiceVarStatusAsync(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *VarName,
        Upnp_FunPtr Fun,
        const void *Cookie);

UPNP_EXPORT_SPEC int UpnpSendAction(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *ServiceType,
        const char *DevUDN,
        IXML_Document *Action,
        IXML_Document **RespNode);

UPNP_EXPORT_SPEC int UpnpSendActionEx(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *ServiceType,
        const char *DevUDN,
        IXML_Document *Header,
        IXML_Document *Action,
        IXML_Document **RespNode);

UPNP_EXPORT_SPEC int UpnpSendActionAsync(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *ServiceType,
        const char *DevUDN,
        IXML_Document *Action,
        Upnp_FunPtr Fun,
        const void *Cookie);

UPNP_EXPORT_SPEC int UpnpSendActionExAsync(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *ServiceType,
        const char *DevUDN,
        IXML_Document *Header,
        IXML_Document *Action,
        Upnp_FunPtr Fun,
        const void *Cookie);

 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                        E V E N T I N G                                     *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/


UPNP_EXPORT_SPEC int UpnpAcceptSubscription(
        UpnpDevice_Handle Hnd,
        const char *DevID,
        const char *ServID,
        const char **VarName,
        const char **NewVal,
        int cVariables,
        const Upnp_SID SubsId);

UPNP_EXPORT_SPEC int UpnpAcceptSubscriptionExt(
        UpnpDevice_Handle Hnd,
        const char *DevID,
        const char *ServID,
        IXML_Document *PropSet,
        const Upnp_SID SubsId);

UPNP_EXPORT_SPEC int UpnpNotify(
        UpnpDevice_Handle,
        const char *DevID,
        const char *ServID,
        const char **VarName,
        const char **NewVal,
        int cVariables);

UPNP_EXPORT_SPEC int UpnpNotifyExt(
        UpnpDevice_Handle,
        const char *DevID,
        const char *ServID,
        IXML_Document *PropSet);

UPNP_EXPORT_SPEC int UpnpRenewSubscription(
        UpnpClient_Handle Hnd,
        int *TimeOut,
        const Upnp_SID SubsId);

UPNP_EXPORT_SPEC int UpnpRenewSubscriptionAsync(
        UpnpClient_Handle Hnd,
        int TimeOut,
        Upnp_SID SubsId,
        Upnp_FunPtr Fun,
        const void *Cookie);

UPNP_EXPORT_SPEC int UpnpSetMaxSubscriptions(
        UpnpDevice_Handle Hnd,
        int MaxSubscriptions);

UPNP_EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut(
        UpnpDevice_Handle Hnd,
        int MaxSubscriptionTimeOut);

UPNP_EXPORT_SPEC int UpnpSubscribe(
        UpnpClient_Handle Hnd,
        const char *PublisherUrl,
        int *TimeOut,
        Upnp_SID SubsId);

UPNP_EXPORT_SPEC int UpnpSubscribeAsync(
        UpnpClient_Handle Hnd,
        const char *PublisherUrl,
        int TimeOut,
        Upnp_FunPtr Fun,
        const void *Cookie);

UPNP_EXPORT_SPEC int UpnpUnSubscribe(
        UpnpClient_Handle Hnd,
        const Upnp_SID SubsId);

UPNP_EXPORT_SPEC int UpnpUnSubscribeAsync(
        UpnpClient_Handle Hnd,
        Upnp_SID SubsId,
        Upnp_FunPtr Fun,
        const void *Cookie);

 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                        C L I E N T - A P I                                 *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/


enum Upnp_HttpMethod_e
{
        UPNP_HTTPMETHOD_PUT = 0,
        UPNP_HTTPMETHOD_DELETE = 1,
        UPNP_HTTPMETHOD_GET = 2,
        UPNP_HTTPMETHOD_HEAD = 3,
        UPNP_HTTPMETHOD_POST = 4
};
 
typedef enum Upnp_HttpMethod_e Upnp_HttpMethod;

UPNP_EXPORT_SPEC int UpnpDownloadUrlItem(
        const char *url,
        char **outBuf,
        char *contentType);

UPNP_EXPORT_SPEC int UpnpOpenHttpGet(
        const char *url,
        void **handle,
        char **contentType,
        int *contentLength,
        int *httpStatus,
        int timeout);

UPNP_EXPORT_SPEC int UpnpOpenHttpGetProxy(
        const char *url,
        const char *proxy_str,
        void **handle,
        char **contentType,
        int *contentLength,
        int *httpStatus,
        int timeout);

UPNP_EXPORT_SPEC int UpnpOpenHttpGetEx(
        const char *url,
        void **handle,
        char **contentType,
        int *contentLength,
        int *httpStatus,
        int lowRange,
        int highRange,
        int timeout);

UPNP_EXPORT_SPEC int UpnpReadHttpGet(
        void *handle,
        char *buf,
        size_t *size,
        int timeout);

UPNP_EXPORT_SPEC int UpnpHttpGetProgress(
        void *handle,
        size_t *length,
        size_t *total);

UPNP_EXPORT_SPEC int UpnpCancelHttpGet(
        void *handle);

UPNP_EXPORT_SPEC int UpnpCloseHttpGet(
        void *handle);

UPNP_EXPORT_SPEC int UpnpOpenHttpPost(
        const char *url,
        void **handle,
        const char *contentType,
        int contentLength,
        int timeout);

UPNP_EXPORT_SPEC int UpnpWriteHttpPost(
        void *handle,
        char *buf,
        size_t *size,
        int timeout);

UPNP_EXPORT_SPEC int UpnpCloseHttpPost(
        void *handle,
        int *httpStatus,
        int timeout);

UPNP_EXPORT_SPEC int UpnpOpenHttpConnection(
        const char *url,
        void **handle,
        int timeout);

UPNP_EXPORT_SPEC int UpnpMakeHttpRequest(
        /* ![in] The method to use to make the request. */
        Upnp_HttpMethod method,
        const char *url,
        void *handle,
        UpnpString *headers,
        const char *contentType,
        int contentLength,
        int timeout);

UPNP_EXPORT_SPEC int UpnpWriteHttpRequest(
        void *handle,
        char *buf,
        size_t *size,
        int timeout);

UPNP_EXPORT_SPEC int UpnpEndHttpRequest(
        void *handle,
        int timeout);

UPNP_EXPORT_SPEC int UpnpGetHttpResponse(
        void *handle,
        UpnpString *headers,
        char **contentType,
        int *contentLength,
        int *httpStatus,
        int timeout);

UPNP_EXPORT_SPEC int UpnpReadHttpResponse(
        void *handle,
        char *buf,
        size_t *size,
        int timeout);

UPNP_EXPORT_SPEC int UpnpCloseHttpConnection(
        void *handle);

UPNP_EXPORT_SPEC int UpnpDownloadXmlDoc(
        const char *url,
        IXML_Document **xmlDoc);

 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                    W E B  S E R V E R  A P I                               *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/


UPNP_EXPORT_SPEC int UpnpSetWebServerRootDir(
        const char *rootDir);

typedef void *UpnpWebFileHandle;

typedef int (*VDCallback_GetInfo)(
        const char *filename,
        UpnpFileInfo *info,
        const void *cookie,
        const void **request_cookie);

UPNP_EXPORT_SPEC int UpnpVirtualDir_set_GetInfoCallback(
        VDCallback_GetInfo callback);

typedef UpnpWebFileHandle (*VDCallback_Open)(
        const char *filename,
        enum UpnpOpenFileMode Mode,
        const void *cookie,
        const void *request_cookie);

UPNP_EXPORT_SPEC int UpnpVirtualDir_set_OpenCallback(VDCallback_Open callback);

typedef int (*VDCallback_Read)(
        UpnpWebFileHandle fileHnd,
        char *buf,
        size_t buflen,
        const void *cookie,
        const void *request_cookie);

UPNP_EXPORT_SPEC int UpnpVirtualDir_set_ReadCallback(VDCallback_Read callback);

typedef int (*VDCallback_Write)(
        UpnpWebFileHandle fileHnd,
        char *buf,
        size_t buflen,
        const void *cookie,
        const void *request_cookie);

UPNP_EXPORT_SPEC int UpnpVirtualDir_set_WriteCallback(
        VDCallback_Write callback);

typedef int (*VDCallback_Seek)(
        UpnpWebFileHandle fileHnd,
        off_t offset,
        int origin,
        const void *cookie,
        const void *request_cookie);

UPNP_EXPORT_SPEC int UpnpVirtualDir_set_SeekCallback(VDCallback_Seek callback);

typedef int (*VDCallback_Close)(
        UpnpWebFileHandle fileHnd,
        const void *cookie,
        const void *request_cookie);

UPNP_EXPORT_SPEC int UpnpVirtualDir_set_CloseCallback(
        VDCallback_Close callback);

UPNP_EXPORT_SPEC int UpnpEnableWebserver(
        int enable);

UPNP_EXPORT_SPEC int UpnpIsWebserverEnabled(void);
 
/*
 * \brief Callback for validating HTTP requests HOST header values.
 *
 * @param hostname the value in the request HOST header.
 * @return An integer representing one of the following:
 *     \li \c UPNP_E_SUCCESS: a request with the HOST header set to hostname
 *                            should be processed.
 *     \li \c UPNP_E_BAD_HTTPMSG the request should be rejected.
 */
typedef int (*WebCallback_HostValidate)(const char *hostname, void *cookie);
 
/*
 * \brief Set callback for validating HTTP requests HOST header values.
 *
 * @param callback the host validating callback function or NULL.
 * @param cookie the chocolate you like.
 */
UPNP_EXPORT_SPEC void UpnpSetHostValidateCallback(
        WebCallback_HostValidate callback, void *cookie);
 
/*
 * \brief Enable or disable literal IP redirection.
 *
 * @param enable Zero to disable (default) non-zero to enable.
 */
UPNP_EXPORT_SPEC void UpnpSetAllowLiteralHostRedirection(int enable);

UPNP_EXPORT_SPEC int UpnpSetWebServerCorsString(
        const char *corsString);

UPNP_EXPORT_SPEC int UpnpAddVirtualDir(
        const char *dirName,
        const void *cookie,
        const void **oldcookie);

UPNP_EXPORT_SPEC int UpnpRemoveVirtualDir(
        const char *dirName);

UPNP_EXPORT_SPEC void UpnpRemoveAllVirtualDirs(void);
 
/* @} Web Server API */
 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
/* @} UPnPAPI UPnP API */
 
#endif /* UPNP_H */