API.hpp

Go to the documentation of this file.

#ifndef COMPA_INC_API_HPP
#define COMPA_INC_API_HPP
/*******************************************************************************
 *
 * Copyright (c) 2000-2003 Intel Corporation
 * All rights reserved.
 * Copyright (C) 2011-2012 France Telecom All rights reserved.
 * Copyright (C) 2021+ GPL 3 and higher by Ingo Höft, <Ingo@Hoeft-online.de>
 * Redistribution only with this Copyright remark. Last modified: 2025-07-08
 *
 * 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.
 *
 ******************************************************************************/
// Last compare with ./Pupnp source file on 2024-08-13, ver 1.14.19
 
#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_SOCKET_ACCEPT -211
 
#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
 
 
/*
 * 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.hpp>
#include <UpnpActionRequest.hpp>
#include <UpnpDiscovery.hpp>
#include <UpnpEvent.hpp>
#include <UpnpEventSubscribe.hpp>
#include <UpnpFileInfo.hpp>
#include <UpnpStateVarComplete.hpp>
#include <UpnpStateVarRequest.hpp>
#include <UpnpSubscriptionRequest.hpp>
 
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.hpp>
 
 
#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                        A D D R E S S I N G                                 *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
PUPNP_Api int UpnpInit2(
    const char* IfName,
    unsigned short DestPort);
 
PUPNP_Api int UpnpFinish(void);
 
PUPNP_Api in_port_t UpnpGetServerPort(void);
 
PUPNP_Api unsigned short UpnpGetServerPort6(void);
 
PUPNP_Api unsigned short UpnpGetServerUlaGuaPort6(void);
 
PUPNP_Api char* UpnpGetServerIpAddress(void);
 
PUPNP_Api char* UpnpGetServerIp6Address(void);
 
PUPNP_Api char* UpnpGetServerUlaGuaIp6Address(void);
 
PUPNP_Api int UpnpRegisterRootDevice(
    const char* const DescUrl,
    const Upnp_FunPtr Fun,
    const void* const Cookie,
    UpnpDevice_Handle* const Hnd);
 
PUPNP_Api int UpnpRegisterRootDevice2(
    const Upnp_DescType descriptionType,
    const char* const description_const,
    const size_t bufferLen,
    const int config_baseURL,
    const Upnp_FunPtr Fun,
    const void* const Cookie,
    UpnpDevice_Handle* const Hnd);
 
PUPNP_Api int UpnpRegisterRootDevice3(
    const char* const DescUrl,
    const Upnp_FunPtr Fun,
    const void* const Cookie,
    UpnpDevice_Handle* const Hnd,
    const int AddressFamily);
 
PUPNP_Api int UpnpRegisterRootDevice4(
    const char* const DescUrl,
    const Upnp_FunPtr Fun,
    const void* const Cookie,
    UpnpDevice_Handle* const Hnd,
    const int AddressFamily,
    const char* const LowerDescUrl);
 
PUPNP_Api int UpnpUnRegisterRootDevice(
    UpnpDevice_Handle Hnd);
 
PUPNP_Api int UpnpUnRegisterRootDeviceLowPower(
    UpnpDevice_Handle Hnd,
    int PowerState,
    int SleepPeriod,
    int RegistrationState);
 
PUPNP_Api int UpnpRegisterClient(
    Upnp_FunPtr Fun,
    const void* Cookie,
    UpnpClient_Handle* Hnd);
 
PUPNP_Api int UpnpUnRegisterClient(
    UpnpClient_Handle Hnd);
 
PUPNP_Api int UpnpSetMaxContentLength(
    size_t contentLength);
 
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                        D I S C O V E R Y                                   *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
PUPNP_Api int UpnpSearchAsync(
    UpnpClient_Handle Hnd,
    int Mx,
    const char* Target_const,
    const void* Cookie_const);
 
PUPNP_Api int UpnpSendAdvertisement(
    UpnpDevice_Handle Hnd,
    int Exp);
 
PUPNP_Api int UpnpSendAdvertisementLowPower(
    UpnpDevice_Handle Hnd,
    int Exp,
    int PowerState,
    int SleepPeriod,
    int RegistrationState);
 
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                          D E S C R I P T I O N                             *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
 
// Nothing available?
 
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                            C O N T R O L                                   *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
PUPNP_Api int UpnpGetServiceVarStatus(
    UpnpClient_Handle Hnd,
    const char* ActionURL_const,
    const char* VarName_const,
    DOMString* StVar);
 
PUPNP_Api int UpnpGetServiceVarStatusAsync(
    UpnpClient_Handle Hnd,
    const char* ActionURL_const,
    const char* VarName_const,
    Upnp_FunPtr Fun,
    const void* Cookie_const);
 
PUPNP_Api int UpnpSendAction(
    UpnpClient_Handle Hnd,
    const char* ActionURL_const,
    const char* ServiceType_const,
    const char* DevUDN_const,
    IXML_Document* Action,
    IXML_Document** RespNodePtr);
 
PUPNP_Api int UpnpSendActionEx(
    UpnpClient_Handle Hnd,
    const char* ActionURL_const,
    const char* ServiceType_const,
    const char* DevUDN_const,
    IXML_Document* Header,
    IXML_Document* Action,
    IXML_Document** RespNodePtr);
 
PUPNP_Api int UpnpSendActionAsync(
    UpnpClient_Handle Hnd,
    const char* ActionURL_const,
    const char* ServiceType_const,
    const char* DevUDN_const,
    IXML_Document* Act,
    Upnp_FunPtr Fun,
    const void* Cookie_const);
 
PUPNP_Api int UpnpSendActionExAsync(
    UpnpClient_Handle Hnd,
    const char* ActionURL_const,
    const char* ServiceType_const,
    const char* DevUDN_const,
    IXML_Document* Header,
    IXML_Document* Act,
    Upnp_FunPtr Fun,
    const void* Cookie_const);
 
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                        E V E N T I N G                                     *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
PUPNP_Api int UpnpAcceptSubscription(
    UpnpDevice_Handle Hnd,
    const char* DevID_const,
    const char* ServName_const,
    const char** VarName_const,
    const char** NewVal_const,
    int cVariables,
    const Upnp_SID SubsId);
 
PUPNP_Api int UpnpAcceptSubscriptionExt(
    UpnpDevice_Handle Hnd,
    const char* DevID_const,
    const char* ServName_const,
    IXML_Document* PropSet,
    const Upnp_SID SubsId);
 
PUPNP_Api int UpnpNotify(
    UpnpDevice_Handle Hnd,
    const char* DevID_const,
    const char* ServName_const,
    const char** VarName_const,
    const char** NewVal_const,
    int cVariables);
 
PUPNP_Api int UpnpNotifyExt(
    UpnpDevice_Handle Hnd,
    const char* DevID_const,
    const char* ServName_const,
    IXML_Document* PropSet);
 
PUPNP_Api int UpnpRenewSubscription(
    UpnpClient_Handle Hnd,
    int* TimeOut,
    const Upnp_SID SubsId);
 
PUPNP_Api int UpnpRenewSubscriptionAsync(
    UpnpClient_Handle Hnd,
    int TimeOut,
    Upnp_SID SubsId,
    Upnp_FunPtr Fun,
    const void* Cookie_const);
 
PUPNP_Api int UpnpSetMaxSubscriptions(
    UpnpDevice_Handle Hnd,
    int MaxSubscriptions);
 
PUPNP_Api int UpnpSetMaxSubscriptionTimeOut(
    UpnpDevice_Handle Hnd,
    int MaxSubscriptionTimeOut);
 
PUPNP_Api int UpnpSubscribe(
    UpnpClient_Handle Hnd,
    const char* EvtUrl_const,
    int* TimeOut,
    Upnp_SID SubsId);
 
PUPNP_Api int UpnpSubscribeAsync(
    UpnpClient_Handle Hnd,
    const char* EvtUrl_const,
    int TimeOut,
    Upnp_FunPtr Fun,
    const void* Cookie_const);
 
PUPNP_Api int UpnpUnSubscribe(
    UpnpClient_Handle Hnd,
    const Upnp_SID SubsId);
 
PUPNP_Api int UpnpUnSubscribeAsync(
    UpnpClient_Handle Hnd,
    Upnp_SID SubsId,
    Upnp_FunPtr Fun,
    const void* Cookie_const);
 
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                        P R E S E N T A T I O N                             *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
 
// Nothing available?
 
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                      C O N T R O L  P O I N T - A P I                      *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
typedef enum {
    UPNP_HTTPMETHOD_PUT,    
    UPNP_HTTPMETHOD_DELETE, 
    UPNP_HTTPMETHOD_GET,    
    UPNP_HTTPMETHOD_HEAD,   
    UPNP_HTTPMETHOD_POST    
} Upnp_HttpMethod;
 
PUPNP_Api int UpnpDownloadUrlItem(
    const char* url,
    char** outBuf,
    char* contentType);
 
PUPNP_Api int UpnpOpenHttpGet(
    const char* url,
    void** handle,
    char** contentType,
    int* contentLength,
    int* httpStatus,
    int timeout);
 
PUPNP_Api int UpnpOpenHttpGetProxy(
    const char* url,
    const char* proxy_str,
    void** handle,
    char** contentType,
    int* contentLength,
    int* httpStatus,
    int timeout);
 
PUPNP_Api int UpnpOpenHttpGetEx(
    const char* url_str,
    void** Handle,
    char** contentType,
    int* contentLength,
    int* httpStatus,
    int lowRange,
    int highRange,
    int timeout);
 
PUPNP_Api int UpnpReadHttpGet(
    void* Handle,
    char* buf,
    size_t* size,
    int timeout);
 
PUPNP_Api int UpnpHttpGetProgress(
    void* Handle,
    size_t* length,
    size_t* total);
 
PUPNP_Api int UpnpCancelHttpGet(
    void* Handle);
 
PUPNP_Api int UpnpCloseHttpGet(
    void* Handle);
 
PUPNP_Api int UpnpOpenHttpPost(
    const char* url,
    void** handle,
    const char* contentType,
    int contentLength,
    int timeout);
 
PUPNP_Api int UpnpWriteHttpPost(
    void* handle,
    char* buf,
    size_t* size,
    int timeout);
 
PUPNP_Api int UpnpCloseHttpPost(
    void* handle,
    int* httpStatus,
    int timeout);
 
PUPNP_Api int UpnpOpenHttpConnection(
    const char* url,
    void** handle,
    int timeout);
 
PUPNP_Api int UpnpMakeHttpRequest(
    Upnp_HttpMethod method,
    const char* url,
    void* handle,
    UpnpString* headers,
    const char* contentType,
    int contentLength,
    int timeout);
 
PUPNP_Api int UpnpWriteHttpRequest(
    void* handle,
    char* buf,
    size_t* size,
    int timeout);
 
PUPNP_Api int UpnpEndHttpRequest(
    void* handle,
    int timeout);
 
PUPNP_Api int UpnpGetHttpResponse(
    void* handle,
    UpnpString* headers,
    char** contentType,
    int* contentLength,
    int* httpStatus,
    int timeout);
 
PUPNP_Api int UpnpReadHttpResponse(
    void* handle,
    char* buf,
    size_t* size,
    int timeout);
 
PUPNP_Api int UpnpCloseHttpConnection(
    void* handle);
 
PUPNP_Api int UpnpDownloadXmlDoc(
    const char* url,
    IXML_Document** xmlDoc);
 
 
 
/******************************************************************************
 ******************************************************************************
 *                                                                            *
 *                    W E B  S E R V E R  A P I                               *
 *                                                                            *
 ******************************************************************************
 ******************************************************************************/
typedef void* UpnpWebFileHandle;
 
typedef int (*VDCallback_GetInfo)(
    const char* filename,
    UpnpFileInfo* info,
    const void* cookie,
    const void** request_cookie);
 
PUPNP_Api int UpnpSetWebServerRootDir(
    const char* rootDir);
 
PUPNP_Api int UpnpVirtualDir_set_GetInfoCallback(VDCallback_GetInfo callback);
 
typedef UpnpWebFileHandle (*VDCallback_Open)(
    const char* filename,
    enum UpnpOpenFileMode Mode,
    const void* cookie,
    const void* request_cookie);
 
PUPNP_Api 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);
 
PUPNP_Api 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);
 
PUPNP_Api 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);
 
PUPNP_Api int UpnpVirtualDir_set_SeekCallback(VDCallback_Seek callback);
 
typedef int (*VDCallback_Close)(
    UpnpWebFileHandle fileHnd,
    const void* cookie,
    const void* request_cookie);
 
PUPNP_Api int UpnpVirtualDir_set_CloseCallback(VDCallback_Close callback);
 
PUPNP_Api int UpnpEnableWebserver(
    int enable);
 
PUPNP_Api int UpnpIsWebserverEnabled(void);
 
typedef int (*WebCallback_HostValidate)(const char* hostname, void* cookie);
 
PUPNP_Api void UpnpSetHostValidateCallback(WebCallback_HostValidate callback,
                                           void* cookie);
 
PUPNP_Api void UpnpSetAllowLiteralHostRedirection(int enable);
 
PUPNP_Api int UpnpSetWebServerCorsString(
    const char* corsString);
 
PUPNP_Api int UpnpAddVirtualDir(
    const char* newDirName,
    const void* cookie,
    const void** oldcookie);
 
PUPNP_Api int UpnpRemoveVirtualDir(
    const char* dirName);
 
PUPNP_Api void UpnpRemoveAllVirtualDirs(void);
 
 
#ifdef __cplusplus
}
#endif /* __cplusplus */
 
#include <upnpconfig.h>
 
#endif // COMPA_INC_API_HPP