upnp.h

Go to the documentation of this file.

//
// Copyright (c) 2000-2003 Intel Corporation 
// 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.
//
/*TU*
    
    TombUPnP - a library for developing UPnP applications.
    
    Copyright (C) 2006-2010 Sergey 'Jin' Bostandzhyan <jin@mediatomb.cc>
    
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License version 2.1 as published by the Free Software Foundation.
    
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.
    
    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
    
    $Id: upnp.h 2081 2010-03-23 20:18:00Z lww $
*/

#ifndef UPNP_H
#define UPNP_H


#include <stdio.h>
#if defined(__FreeBSD__) || defined(__APPLE__) || defined(__NetBSD__)
#include <time.h>
#include <sys/types.h>
#endif
#include "ixml.h"
#include "upnpconfig.h"
#if UPNP_HAVE_DEBUG
#       include "upnpdebug.h"
#endif

#ifdef WIN32
 #ifndef UPNP_STATIC_LIB
  #ifdef LIBUPNP_EXPORTS
   // set up declspec for dll export to make functions visible to library users
   #define EXPORT_SPEC __declspec(dllexport)
  #else
   #define EXPORT_SPEC __declspec(dllimport)
  #endif
 #else
  #define EXPORT_SPEC
 #endif
#else
 #define EXPORT_SPEC
#endif

#ifndef WIN32
 #define UpnpCloseSocket         close
#else
 #define UpnpCloseSocket         closesocket
#endif
#define UPNP_SOCKETERROR        -1
#define UPNP_INVALID_SOCKET     -1
#ifndef WIN32
 #define SOCKET                  int
#endif

#ifndef WIN32
 #include <netinet/in.h>
#else
 #include <winsock2.h>
 #include <time.h>
#endif

#define NUM_HANDLE 200
#define LINE_SIZE  180
#define NAME_SIZE  256
#define HEADER_SIZE  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_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


#ifndef OUT
#define OUT
#endif

#ifndef IN
#define IN
#endif

#ifndef INOUT
#define INOUT
#endif

enum UpnpOpenFileMode{UPNP_READ, UPNP_WRITE};



typedef int  UpnpClient_Handle;

typedef int  UpnpDevice_Handle;

enum Upnp_EventType_e {

  //
  // Control callbacks
  //

  UPNP_CONTROL_ACTION_REQUEST,

  UPNP_CONTROL_ACTION_COMPLETE,

  UPNP_CONTROL_GET_VAR_REQUEST,

  UPNP_CONTROL_GET_VAR_COMPLETE,

  //
  // Discovery callbacks
  //

  UPNP_DISCOVERY_ADVERTISEMENT_ALIVE,

  UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE,

  UPNP_DISCOVERY_SEARCH_RESULT,

  UPNP_DISCOVERY_SEARCH_TIMEOUT,

  //
  // Eventing callbacks
  //

  UPNP_EVENT_SUBSCRIPTION_REQUEST,

  UPNP_EVENT_RECEIVED,

  UPNP_EVENT_RENEWAL_COMPLETE,

  UPNP_EVENT_SUBSCRIBE_COMPLETE,

  UPNP_EVENT_UNSUBSCRIBE_COMPLETE,

  UPNP_EVENT_AUTORENEWAL_FAILED,

  UPNP_EVENT_SUBSCRIPTION_EXPIRED

};

typedef enum Upnp_EventType_e Upnp_EventType;

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;

struct Upnp_Action_Request
{
  int ErrCode;

  int Socket;

  char ErrStr[LINE_SIZE];

  char ActionName[NAME_SIZE];

  char DevUDN[NAME_SIZE];

  char ServiceID[NAME_SIZE];

  IXML_Document *ActionRequest;

  IXML_Document *ActionResult;

  struct in_addr CtrlPtIPAddr;

  IXML_Document *SoapHeader;
};

struct Upnp_Action_Complete
{
  int ErrCode;

  char CtrlUrl[NAME_SIZE];

  IXML_Document *ActionRequest;

  IXML_Document *ActionResult;

};

struct Upnp_State_Var_Request
{
  int ErrCode;

  int Socket;

  char ErrStr[LINE_SIZE];

  char DevUDN[NAME_SIZE];

  char ServiceID[NAME_SIZE];

  char StateVarName[NAME_SIZE];

  struct in_addr CtrlPtIPAddr;

  DOMString CurrentVal;
};

struct Upnp_State_Var_Complete
{
  int ErrCode;

  char CtrlUrl[NAME_SIZE];

  char StateVarName[NAME_SIZE];

  DOMString CurrentVal;
};

struct Upnp_Event
{
  Upnp_SID Sid;

  int EventKey;

  IXML_Document *ChangedVariables;

};

//
// This typedef is required by Doc++ to parse the last entry of the 
// Upnp_Discovery structure correctly.
//

typedef struct sockaddr_in SOCKADDRIN;

struct Upnp_Discovery
{

  int  ErrCode;                  
                                     
  int  Expires;                  
                                     
  char DeviceId[LINE_SIZE];      

  char DeviceType[LINE_SIZE];    

  char ServiceType[LINE_SIZE];

  char ServiceVer[LINE_SIZE];    

  char Location[LINE_SIZE];      

  char Os[LINE_SIZE];            
                                     
  char Date[LINE_SIZE];            
                                     
  char Ext[LINE_SIZE];           
                                     
  SOCKADDRIN * DestAddr; 

};

struct Upnp_Event_Subscribe {

  Upnp_SID Sid;            

  int ErrCode;              

  char PublisherUrl[NAME_SIZE]; 

  int TimeOut;              
                              
};
  
struct Upnp_Subscription_Request
{
  char *ServiceId; 

  char *UDN;       

  Upnp_SID Sid;

};


struct File_Info
{
  off_t file_length;

  time_t last_modified;

  int is_directory;

  int is_readable;

  int force_chunked;

  DOMString content_type;
 
  DOMString http_header;

};

/* The type of handle returned by the web server for open requests. */

typedef void *UpnpWebFileHandle;

struct UpnpVirtualDirCallbacks
{
  int (*get_info) (
    IN  const char *filename,     
    OUT struct File_Info *info    
    );
                                  
  UpnpWebFileHandle (*open)(
    IN const char *filename,       
    OUT struct File_Info *info,    
    IN enum UpnpOpenFileMode Mode  
    );

   int (*read) (
     IN UpnpWebFileHandle fileHnd,  
     OUT char *buf,                 
     IN size_t buflen               
     );

   int (*write) (
     IN UpnpWebFileHandle fileHnd, 
     IN char *buf,                 
     IN size_t buflen              
     );

   int (*seek) (
     IN UpnpWebFileHandle fileHnd,  
     IN off_t offset,                
     IN int origin                  
     );

   int (*close) (
     IN UpnpWebFileHandle fileHnd   
     );

};

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

typedef struct user_HTTP_Header_List
{
    struct user_HTTP_Header_List *next;
    char header[HEADER_SIZE];
} userHTTPHeaderList;


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


#ifdef __cplusplus
extern "C" {
#endif // __cplusplus



EXPORT_SPEC int UpnpInit(
    IN const char *HostIP,      
    IN unsigned short DestPort, 
    IN int maxHTTPTimeoutRetries, 
    IN void *thread_cleanup  
    );

EXPORT_SPEC int UpnpFinish();

EXPORT_SPEC unsigned short UpnpGetServerPort(void);

EXPORT_SPEC char * UpnpGetServerIpAddress(void);

EXPORT_SPEC int UpnpRegisterClient(
    IN Upnp_FunPtr Callback,   
    IN const void *Cookie,     
    OUT UpnpClient_Handle *Hnd 
    );  

EXPORT_SPEC int UpnpRegisterRootDevice(
    IN const char *DescUrl,    
    IN Upnp_FunPtr Callback,   
    IN const void *Cookie,     
    OUT UpnpDevice_Handle *Hnd 
    );

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

EXPORT_SPEC int UpnpUnRegisterClient(
    IN UpnpClient_Handle Hnd  
    );

EXPORT_SPEC int UpnpUnRegisterRootDevice(
   IN UpnpDevice_Handle 
   );


EXPORT_SPEC int UpnpSetContentLength(
    IN UpnpClient_Handle Hnd,  
    IN int contentLength       
    );


EXPORT_SPEC int UpnpSetMaxContentLength(
    IN size_t contentLength    
    );


//                                                                    //
//                        D I S C O V E R Y                           //
//                                                                    //



EXPORT_SPEC int UpnpSearchAsync(
    IN UpnpClient_Handle Hnd, 
    IN int Mx,                
    IN const char *Target,    
    IN const void *Cookie     
    ); 

EXPORT_SPEC int UpnpSendAdvertisement(
    IN UpnpDevice_Handle Hnd, 
    IN int Exp                
    );


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



EXPORT_SPEC int UpnpGetServiceVarStatus(
    IN UpnpClient_Handle Hnd,     
    IN const char *ActionURL,     
    IN const char *VarName,       
    OUT DOMString *StVarVal       
    );

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

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

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

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

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


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



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

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

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

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

EXPORT_SPEC int UpnpRenewSubscription(
    IN UpnpClient_Handle Hnd, 
    INOUT int *TimeOut,       
    IN Upnp_SID SubsId        
    );

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

EXPORT_SPEC int UpnpSetMaxSubscriptions(  
    IN UpnpDevice_Handle Hnd, 
    IN int MaxSubscriptions   
    );

EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut(  
    IN UpnpDevice_Handle Hnd,       
    IN int MaxSubscriptionTimeOut   
    );

EXPORT_SPEC int UpnpSubscribe(
    IN UpnpClient_Handle Hnd,    
    IN const char *PublisherUrl, 
    INOUT int *TimeOut,          
    OUT Upnp_SID SubsId          
    );

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

EXPORT_SPEC int UpnpUnSubscribe(
    IN UpnpClient_Handle Hnd, 
    IN Upnp_SID SubsId        
    );

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



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



EXPORT_SPEC int UpnpDownloadUrlItem(
    IN const char *url,          
    OUT char **outBuf,           
    OUT char *contentType        
    );

EXPORT_SPEC int UpnpOpenHttpGet(
        IN const char *url,         
        IN OUT void **handle,       
        IN OUT char **contentType,  
        IN OUT off_t *contentLength,  
        IN OUT int *httpStatus,     
        IN int timeout              
          );

EXPORT_SPEC int UpnpOpenHttpGetProxy(
        IN const char *url,         
    IN const char *proxy_str,    
        IN OUT void **handle,       
        IN OUT char **contentType,  
        IN OUT off_t *contentLength,  
        IN OUT int *httpStatus,     
        IN int timeout              
          );

EXPORT_SPEC int UpnpOpenHttpGetEx(
        IN const char *url,         
        IN OUT void **handle,       
        IN OUT char **contentType,  
        IN OUT off_t *contentLength,  
        IN OUT int *httpStatus,     
        IN int lowRange,            
        IN int highRange,           
        IN int timeout              
          );

EXPORT_SPEC int UpnpReadHttpGet(
        IN void *handle,           
        IN OUT char *buf,          
        IN OUT off_t *size, 
        IN int timeout             
        );

EXPORT_SPEC int UpnpHttpGetProgress(
    IN void *handle,           
        OUT off_t *length, 
        OUT off_t *total   
    );


EXPORT_SPEC int UpnpCancelHttpGet(IN void *handle);

EXPORT_SPEC int UpnpCloseHttpGet(IN void *handle);


EXPORT_SPEC int UpnpOpenHttpPost(
        IN const char *url,         
        IN OUT void **handle,       
        IN const char *contentType, 
        IN int contentLength,       
        IN int timeout              
        );


EXPORT_SPEC int UpnpWriteHttpPost(
        IN void *handle,          
        IN char *buf,             
        IN off_t *size,    
        IN int timeout            
        );

EXPORT_SPEC int UpnpCloseHttpPost(
        IN void *handle,          
        IN OUT int *httpStatus,   
        IN int timeout            
        );
  

EXPORT_SPEC int UpnpDownloadXmlDoc(
    IN const char *url,          
    OUT IXML_Document **xmlDoc   
    );


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



EXPORT_SPEC int UpnpSetWebServerRootDir( 
    IN const char* rootDir  
    );

EXPORT_SPEC int UpnpAddCustomHTTPHeader( 
    IN const char* header_string  
    );

EXPORT_SPEC int UpnpRemoveCustomHTTPHeader( 
    IN const char* header_string  
    );

EXPORT_SPEC void UpnpRemoveAllCustomHTTPHeaders( );


EXPORT_SPEC int UpnpSetVirtualDirCallbacks(
    IN struct UpnpVirtualDirCallbacks *callbacks 
    );

EXPORT_SPEC int UpnpEnableWebserver(
    IN int enable 
    );

EXPORT_SPEC int UpnpIsWebserverEnabled();

EXPORT_SPEC int UpnpAddVirtualDir(
    IN const char *dirName 
    );

EXPORT_SPEC int UpnpRemoveVirtualDir(
    IN const char *dirName 
    );

EXPORT_SPEC void UpnpRemoveAllVirtualDirs( );

EXPORT_SPEC void UpnpFree(
    IN void *item /* The item to free. */
    );


#ifdef __cplusplus
}
#endif // __cplusplus


#endif

---