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 "ixml.h"
#include "upnpconfig.h"
#include "UpnpGlobal.h"
#include "UpnpInet.h"
 
/*
 * \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 "ActionComplete.h"
#include "ActionRequest.h"
#include "Discovery.h"
#include "Event.h"
#include "EventSubscribe.h"
#include "FileInfo.h"
#include "StateVarComplete.h"
#include "StateVarRequest.h"
#include "SubscriptionRequest.h"
 
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 */
 
EXPORT_SPEC int UpnpInit2( 
        const char *IfName,
        unsigned short DestPort);
 
#ifdef UPNP_ENABLE_OPEN_SSL
EXPORT_SPEC int UpnpInitSslContext(
        int initOpenSslLib,
        const SSL_METHOD *sslMethod);
#endif
 
EXPORT_SPEC int UpnpFinish(void);
 
EXPORT_SPEC unsigned short UpnpGetServerPort(void);
 
EXPORT_SPEC unsigned short UpnpGetServerPort6(void);
EXPORT_SPEC char *UpnpGetServerIpAddress(void);
 
EXPORT_SPEC char *UpnpGetServerIp6Address(void);
 
EXPORT_SPEC char *UpnpGetServerUlaGuaIp6Address(void);
EXPORT_SPEC int UpnpRegisterRootDevice(
        const char *DescUrl,
        Upnp_FunPtr Callback,
        const void *Cookie,
        UpnpDevice_Handle *Hnd);
 
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);
 
EXPORT_SPEC int UpnpRegisterRootDevice3(
        const char *DescUrl,
        Upnp_FunPtr Callback,
        const void *Cookie,
        UpnpDevice_Handle *Hnd,
        int  AddressFamily);
 
EXPORT_SPEC int UpnpRegisterRootDevice4(
        const char *DescUrl,
        Upnp_FunPtr Callback,
        const void *Cookie,
        UpnpDevice_Handle *Hnd,
        int  AddressFamily,
        const char *LowerDescUrl);
 
EXPORT_SPEC int UpnpUnRegisterRootDevice(
        UpnpDevice_Handle Hnd);
 
EXPORT_SPEC int UpnpUnRegisterRootDeviceLowPower(
        UpnpDevice_Handle Hnd,
        int PowerState,
        int SleepPeriod,
        int RegistrationState);
 
EXPORT_SPEC int UpnpRegisterClient(
        Upnp_FunPtr Callback,
        const void *Cookie,
        UpnpClient_Handle *Hnd);
 
EXPORT_SPEC int UpnpUnRegisterClient(
        UpnpClient_Handle Hnd);
 
EXPORT_SPEC int UpnpSetContentLength(
        UpnpClient_Handle Hnd,
        size_t contentLength);
 
EXPORT_SPEC int UpnpSetMaxContentLength(
        size_t contentLength);
 
/* @} Initialization and Registration */
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                        D I S C O V E R Y                                   *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
 
EXPORT_SPEC int UpnpSearchAsync(
        UpnpClient_Handle Hnd,
        int Mx,
        const char *TTarget_constarget_const,
        const void *Cookie_const);
 
EXPORT_SPEC int UpnpSendAdvertisement(
        UpnpDevice_Handle Hnd,
        int Exp);
 
EXPORT_SPEC int UpnpSendAdvertisementLowPower(
        UpnpDevice_Handle Hnd,
        int Exp,
        int PowerState,
        int SleepPeriod,
        int RegistrationState);
 
/* @} Discovery */
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                            C O N T R O L                                   *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
 
EXPORT_SPEC int UpnpGetServiceVarStatus(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *VarName,
        DOMString *StVarVal);
 
EXPORT_SPEC int UpnpGetServiceVarStatusAsync(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *VarName,
        Upnp_FunPtr Fun,
        const void *Cookie);
 
EXPORT_SPEC int UpnpSendAction(
        UpnpClient_Handle Hnd,
        const char *ActionURL,
        const char *ServiceType,
        const char *DevUDN,
        IXML_Document *Action,
        IXML_Document **RespNode);
 
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);
 
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);
 
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                                     *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
 
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);
 
EXPORT_SPEC int UpnpAcceptSubscriptionExt(
        UpnpDevice_Handle Hnd,
        const char *DevID,
        const char *ServID,
        IXML_Document *PropSet,
        const Upnp_SID SubsId);
 
EXPORT_SPEC int UpnpNotify(
        UpnpDevice_Handle,
        const char *DevID,
        const char *ServID,
        const char **VarName,
        const char **NewVal,
        int cVariables);
 
EXPORT_SPEC int UpnpNotifyExt(
        UpnpDevice_Handle,
        const char *DevID,
        const char *ServID,
        IXML_Document *PropSet);
 
EXPORT_SPEC int UpnpRenewSubscription(
        UpnpClient_Handle Hnd,
        int *TimeOut,
        const Upnp_SID SubsId);
 
EXPORT_SPEC int UpnpRenewSubscriptionAsync(
        UpnpClient_Handle Hnd,
        int TimeOut,
        Upnp_SID SubsId,
        Upnp_FunPtr Fun,
        const void *Cookie);
 
EXPORT_SPEC int UpnpSetMaxSubscriptions(  
        UpnpDevice_Handle Hnd,
        int MaxSubscriptions);
 
EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut(  
        UpnpDevice_Handle Hnd,
        int MaxSubscriptionTimeOut);
 
EXPORT_SPEC int UpnpSubscribe(
        UpnpClient_Handle Hnd,
        const char *PublisherUrl,
        int *TimeOut,
        Upnp_SID SubsId);
 
EXPORT_SPEC int UpnpSubscribeAsync(
        UpnpClient_Handle Hnd,
        const char *PublisherUrl,
        int TimeOut,
        Upnp_FunPtr Fun,
        const void *Cookie);
 
EXPORT_SPEC int UpnpUnSubscribe(
        UpnpClient_Handle Hnd,
        const Upnp_SID SubsId);
 
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;
 
EXPORT_SPEC int UpnpDownloadUrlItem(
        const char *url,
        char **outBuf,
        char *contentType);
 
EXPORT_SPEC int UpnpOpenHttpGet(
        const char *url,
        void **handle,
        char **contentType,
        int *contentLength,
        int *httpStatus,
        int timeout);
 
EXPORT_SPEC int UpnpOpenHttpGetProxy(
        const char *url,
        const char *proxy_str,
        void **handle,
        char **contentType,
        int *contentLength,
        int *httpStatus,
        int timeout);
 
EXPORT_SPEC int UpnpOpenHttpGetEx(
        const char *url,
        void **handle,
        char **contentType,
        int *contentLength,
        int *httpStatus,
        int lowRange,
        int highRange,
        int timeout);
 
EXPORT_SPEC int UpnpReadHttpGet(
        void *handle,
        char *buf,
        size_t *size,
        int timeout);
 
EXPORT_SPEC int UpnpHttpGetProgress(
        void *handle,
        size_t *length,
        size_t *total);
 
EXPORT_SPEC int UpnpCancelHttpGet(
        void *handle);
 
EXPORT_SPEC int UpnpCloseHttpGet(
        void *handle);
 
EXPORT_SPEC int UpnpOpenHttpPost(
        const char *url,
        void **handle,
        const char *contentType,
        int contentLength,
        int timeout);
 
EXPORT_SPEC int UpnpWriteHttpPost(
        void *handle,
        char *buf,
        size_t *size,
        int timeout);
 
EXPORT_SPEC int UpnpCloseHttpPost(
        void *handle,
        int *httpStatus,
        int timeout);
 
EXPORT_SPEC int UpnpOpenHttpConnection(
        const char *url,
        void **handle,
        int timeout);
 
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);
 
EXPORT_SPEC int UpnpWriteHttpRequest(
        void *handle,
        char *buf,
        size_t *size,
        int timeout);
 
EXPORT_SPEC int UpnpEndHttpRequest(
        void *handle,
        int timeout);
 
EXPORT_SPEC int UpnpGetHttpResponse(
        void *handle,
        UpnpString *headers,
        char **contentType,
        int *contentLength,
        int *httpStatus,
        int timeout);
 
EXPORT_SPEC int UpnpReadHttpResponse(
        void *handle,
        char *buf,
        size_t *size,
        int timeout);
 
EXPORT_SPEC int UpnpCloseHttpConnection(
        void *handle);
 
EXPORT_SPEC int UpnpDownloadXmlDoc(
        const char *url,
        IXML_Document **xmlDoc);
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                    W E B  S E R V E R  A P I                               *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
 
EXPORT_SPEC int UpnpSetWebServerRootDir( 
        const char *rootDir);
 
typedef void *UpnpWebFileHandle;
 
typedef int (*VDCallback_GetInfo)(
                const char *filename,
                UpnpFileInfo *info,
                const void *cookie);
 
EXPORT_SPEC int UpnpVirtualDir_set_GetInfoCallback(VDCallback_GetInfo callback);
 
typedef UpnpWebFileHandle (*VDCallback_Open)(
                const char *filename,
                enum UpnpOpenFileMode Mode,
                const void *cookie);
 
EXPORT_SPEC int UpnpVirtualDir_set_OpenCallback(VDCallback_Open callback);
 
typedef int (*VDCallback_Read)(
        UpnpWebFileHandle fileHnd,
        char *buf,
        size_t buflen,
        const void *cookie);
 
EXPORT_SPEC int UpnpVirtualDir_set_ReadCallback(VDCallback_Read callback);
 
typedef int (*VDCallback_Write)(
        UpnpWebFileHandle fileHnd,
        char *buf,
        size_t buflen,
        const void *cookie);
 
EXPORT_SPEC int UpnpVirtualDir_set_WriteCallback(VDCallback_Write callback);
 
typedef int (*VDCallback_Seek) (
        UpnpWebFileHandle fileHnd,
        off_t offset,
        int origin,
        const void *cookie);
 
EXPORT_SPEC int UpnpVirtualDir_set_SeekCallback(VDCallback_Seek callback);
 
typedef int (*VDCallback_Close)(
                UpnpWebFileHandle fileHnd,
                const void *cookie);
 
EXPORT_SPEC int UpnpVirtualDir_set_CloseCallback(VDCallback_Close callback);
 
EXPORT_SPEC int UpnpEnableWebserver(
        int enable);
 
EXPORT_SPEC int UpnpIsWebserverEnabled(void);
 
EXPORT_SPEC int UpnpAddVirtualDir(
        const char *dirName,
        const void *cookie,
        const void **oldcookie);
 
EXPORT_SPEC int UpnpRemoveVirtualDir(
        const char *dirName);
 
EXPORT_SPEC void UpnpRemoveAllVirtualDirs(void);
 
/* @} Web Server API */
 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
/* @} UPnPAPI UPnP API */
 
#endif /* UPNP_H */