Logo Search packages:      
Sourcecode: libupnp4 version File versions  Download package

gena.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.
 *
 ******************************************************************************/


#ifndef GENA_H
#define GENA_H


/*!
 * \file
 */


#include "config.h"


#include <string.h>
#include <time.h>


#include "client_table.h"
#include "httpparser.h"
#include "miniserver.h"
#include "service_table.h"
#include "sock.h"
#include "ThreadPool.h"
#include "upnp.h"
#include "UpnpString.h"
#include "uri.h"


#ifdef __cplusplus
      #define EXTERN_C extern "C"
#else /* __cplusplus */
      #ifndef EXTERN_C
            #define EXTERN_C 
      #endif /* EXTERN_C */
#endif /* __cplusplus */


/*!
 * \brief XML version comment. Not used because it is not interopeable with
 * other UPnP vendors.
 */
00073 #define XML_VERSION "<?xml version='1.0' encoding='ISO-8859-1' ?>\n"
#define XML_PROPERTYSET_HEADER \
      "<e:propertyset xmlns:e=\"urn:schemas-upnp-org:event-1-0\">\n"


#define UNABLE_MEMORY "HTTP/1.1 500 Internal Server Error\r\n\r\n"
#define UNABLE_SERVICE_UNKNOWN "HTTP/1.1 404 Not Found\r\n\r\n"
#define UNABLE_SERVICE_NOT_ACCEPT "HTTP/1.1 503 Service Not Available\r\n\r\n"


#define NOT_IMPLEMENTED "HTTP/1.1 501 Not Implemented\r\n\r\n"
#define BAD_REQUEST "HTTP/1.1 400 Bad Request\r\n\r\n"
#define INVALID_NT BAD_CALLBACK
#define BAD_CALLBACK "HTTP/1.1 412 Precondition Failed\r\n\r\n" 
#define HTTP_OK_CRLF "HTTP/1.1 200 OK\r\n\r\n"
#define HTTP_OK_STR "HTTP/1.1 200 OK\r\n"
#define INVALID_SID BAD_CALLBACK
#define MISSING_SID BAD_CALLBACK
#define MAX_CONTENT_LENGTH 20
#define MAX_SECONDS 10
#define MAX_EVENTS 20
#define MAX_PORT_SIZE 10


#define GENA_E_BAD_RESPONSE UPNP_E_BAD_RESPONSE
#define GENA_E_BAD_SERVICE UPNP_E_INVALID_SERVICE
#define GENA_E_SUBSCRIPTION_UNACCEPTED UPNP_E_SUBSCRIBE_UNACCEPTED
#define GENA_E_BAD_SID UPNP_E_INVALID_SID
#define GENA_E_UNSUBSCRIBE_UNACCEPTED UPNP_E_UNSUBSCRIBE_UNACCEPTED
#define GENA_E_NOTIFY_UNACCEPTED UPNP_E_NOTIFY_UNACCEPTED
#define GENA_E_NOTIFY_UNACCEPTED_REMOVE_SUB -9
#define GENA_E_BAD_HANDLE UPNP_E_INVALID_HANDLE


#define XML_ERROR -5
#define XML_SUCCESS UPNP_E_SUCCESS
#define GENA_SUCCESS UPNP_E_SUCCESS


#define CALLBACK_SUCCESS 0
#define DEFAULT_TIMEOUT 1801


extern ithread_mutex_t GlobalClientSubscribeMutex;


/*!
 * \brief Locks the subscription.
 */
00122 #define SubscribeLock() \
      UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
            "Trying Subscribe Lock");  \
      ithread_mutex_lock(&GlobalClientSubscribeMutex); \
      UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
            "Subscribe Lock");


/*!
 * \brief Unlocks the subscription.
 */
00133 #define SubscribeUnlock() \
      UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
            "Trying Subscribe UnLock"); \
      ithread_mutex_unlock(&GlobalClientSubscribeMutex); \
      UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
            "Subscribe UnLock");


/*!
 * Structure to send NOTIFY message to all subscribed control points
 */
00144 typedef struct NOTIFY_THREAD_STRUCT {
      char *headers;
      DOMString propertySet;
      char *servId;
      char *UDN;
      Upnp_SID sid;
      int eventKey;
      int *reference_count;
      UpnpDevice_Handle device_handle;
} notify_thread_struct;


/*!
 * \brief This is the callback function called by the miniserver to handle
 *    incoming GENA requests.
 *
 * \return UPNP_E_SUCCESS if successful, otherwise appropriate error code.
 */
EXTERN_C void genaCallback(
      /*! [in] represents the parse state of the request */
      http_parser_t *parser, 
      /*! [in] HTTP message containing GENA request */
      http_message_t* request,
      /*! [in,out] Structure containing information about the socket */
      SOCKINFO *info);

 
/*!
 * \brief This function subscribes to a PublisherURL (also mentioned as EventURL
 * in some places).
 *
 * It sends SUBSCRIBE http request to service processes request. Finally adds a
 * Subscription to the clients subscription list, if service responds with OK.
 *
 * \return UPNP_E_SUCCESS if service response is OK, otherwise returns the 
 *    appropriate error code
 */
#ifdef INCLUDE_CLIENT_APIS
EXTERN_C int genaSubscribe(
      /*! [in] The client handle. */
      UpnpClient_Handle client_handle,
      /*! [in] Of the form: "http://134.134.156.80:4000/RedBulb/Event */
      const UpnpString *PublisherURL,
      /*! [in,out] requested Duration:
       * \li if -1, then "infinite".
       * \li in the OUT case: actual Duration granted by Service,
       *    -1 for infinite. */
      int *TimeOut,
      /*! [out] sid of subscription, memory passed in by caller. */
      UpnpString *out_sid);
#endif /* INCLUDE_CLIENT_APIS */


/*!
 * \brief Unsubscribes a SID.
 *
 * It first validates the SID and client_handle,copies the subscription, sends
 * UNSUBSCRIBE http request to service processes request and finally removes
 * the subscription.
 *
 * \return UPNP_E_SUCCESS if service response is OK, otherwise returns the
 *    appropriate error code.
 */
#ifdef INCLUDE_CLIENT_APIS
EXTERN_C int genaUnSubscribe(
      /*! [in] UPnP client handle. */
      UpnpClient_Handle client_handle,
      /*! [in] The subscription ID. */
      const UpnpString *in_sid);
#endif /* INCLUDE_CLIENT_APIS */


/*!
 * \brief Unsubcribes all the outstanding subscriptions and cleans the
 *    subscription list.
 *
 * This function is called when control point unregisters.
 *
 * \returns UPNP_E_SUCCESS if successful, otherwise returns the appropriate
 *    error code.
 */
#ifdef INCLUDE_CLIENT_APIS
EXTERN_C int genaUnregisterClient(
      /*! [in] Handle containing all the control point related information. */
      UpnpClient_Handle client_handle);
#endif /* INCLUDE_CLIENT_APIS */


/*
 * DEVICE
 */


/*!
 * \brief Cleans the service table of the device.
 *
 * \return UPNP_E_SUCCESS if successful, otherwise returns GENA_E_BAD_HANDLE
 */
#ifdef INCLUDE_DEVICE_APIS
EXTERN_C int genaUnregisterDevice(
      /*! [in] Handle of the root device */
      UpnpDevice_Handle device_handle);
#endif /* INCLUDE_CLIENT_APIS */


/*!
 * \brief Renews a SID.
 *
 * It first validates the SID and client_handle and copies the subscription.
 * It sends RENEW (modified SUBSCRIBE) http request to service and processes
 * the response.
 *
 * \return UPNP_E_SUCCESS if service response is OK, otherwise the
 *    appropriate error code.
 */
#ifdef INCLUDE_CLIENT_APIS
EXTERN_C int genaRenewSubscription(
      /*! [in] Client handle. */
      UpnpClient_Handle client_handle,
      /*! [in] Subscription ID. */
      const UpnpString *in_sid,
      /*! [in,out] requested Duration, if -1, then "infinite". In the OUT case:
       * actual Duration granted by Service, -1 for infinite. */
      int *TimeOut);
#endif /* INCLUDE_CLIENT_APIS */


/*!
 * \brief Sends a notification to all the subscribed control points.
 *
 * \return int
 *
 * \note This function is similar to the genaNotifyAllExt. The only difference
 *    is it takes event variable array instead of xml document.
 */
#ifdef INCLUDE_DEVICE_APIS
EXTERN_C int genaNotifyAll(
      /*! [in] Device handle. */
      UpnpDevice_Handle device_handle,
      /*! [in] Device udn. */
      char *UDN,
      /*! [in] Service ID. */
      char *servId,
      /*! [in] Array of varible names. */
      char **VarNames,
      /*! [in] Array of variable values. */
      char **VarValues,
      /*! [in] Number of variables. */
      int var_count);
#endif /* INCLUDE_DEVICE_APIS */


/*!
 * \brief Sends a notification to all the subscribed control points.
 *
 * \return int
 *
 * \note This function is similar to the genaNotifyAll. the only difference
 *    is it takes the document instead of event variable array.
 */
#ifdef INCLUDE_DEVICE_APIS
EXTERN_C int genaNotifyAllExt(
      /*! [in] Device handle. */
      UpnpDevice_Handle device_handle, 
      /*! [in] Device udn. */
      char *UDN,
      /*! [in] Service ID. */
      char *servId,
      /*! [in] XML document Event varible property set. */
      IXML_Document *PropSet);
#endif /* INCLUDE_DEVICE_APIS */


/*!
 * \brief Sends the intial state table dump to newly subscribed control point.
 *
 * \return GENA_E_SUCCESS if successful, otherwise the appropriate error code.
 * 
 * \note  No other event will be sent to this control point before the 
 *    intial state table dump.
 */
#ifdef INCLUDE_DEVICE_APIS
EXTERN_C int genaInitNotify(
      /*! [in] Device handle. */
      UpnpDevice_Handle device_handle,
      /*! [in] Device udn. */
      char *UDN,
      /*! [in] Service ID. */
      char *servId,
      /*! [in] Array of variable names. */
      char **VarNames,
      /*! [in] Array of variable values. */
      char **VarValues,
      /*! [in] Array size. */
      int var_count,
      /*! [in] Subscription ID. */
      const Upnp_SID sid);
#endif /* INCLUDE_DEVICE_APIS */


/*!
 * \brief Similar to the genaInitNofity. The only difference is that it
 * takes the xml document for the state table and sends the intial state
 * table dump to newly subscribed control point.
 *
 * \return GENA_E_SUCCESS if successful, otherwise the appropriate error code.
 * 
 * \note No other event will be sent to this control point before the 
 *    intial state table dump.
 */
#ifdef INCLUDE_DEVICE_APIS
EXTERN_C  int genaInitNotifyExt(
      /*! [in] Device handle. */
      UpnpDevice_Handle device_handle, 
      /*! [in] Device udn. */
      char *UDN, 
      /*! [in] Service ID. */
      char *servId,
      /*! [in] Document of the state table. */
      IXML_Document *PropSet, 
      /*! [in] subscription ID. */
      const Upnp_SID sid);
#endif /* INCLUDE_DEVICE_APIS */


/*!
 * \brief Sends an error message to the control point in the case of incorrect
 *    GENA requests.
 *
 * \return UPNP_E_SUCCESS if successful, otherwise appropriate error code.
 */
void error_respond(
      /*! [in] Structure containing information about the socket. */
      SOCKINFO *info,
      /*! [in] error code that will be in the GENA response. */
      int error_code,
      /*! [in] GENA request Packet. */
      http_message_t* hmsg);


#endif /* GENA_H */


Generated by  Doxygen 1.6.0   Back to index