Data Structures | Defines | Typedefs | Functions | Variables

gena.h File Reference

#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"
Include dependency graph for gena.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  NOTIFY_THREAD_STRUCT

Defines

#define EXTERN_C
#define XML_VERSION   "<?xml version='1.0' encoding='ISO-8859-1' ?>\n"
 XML version comment. Not used because it is not interopeable with other UPnP vendors.
#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
#define SubscribeLock()
 Locks the subscription.
#define SubscribeUnlock()
 Unlocks the subscription.

Typedefs

typedef struct NOTIFY_THREAD_STRUCT notify_thread_struct

Functions

void genaCallback (http_parser_t *parser, http_message_t *request, SOCKINFO *info)
 This is the callback function called by the miniserver to handle incoming GENA requests.
int genaSubscribe (UpnpClient_Handle client_handle, const UpnpString *PublisherURL, int *TimeOut, UpnpString *out_sid)
 This function subscribes to a PublisherURL (also mentioned as EventURL in some places).
int genaUnSubscribe (UpnpClient_Handle client_handle, const UpnpString *in_sid)
 Unsubscribes a SID.
int genaUnregisterClient (UpnpClient_Handle client_handle)
 Unsubcribes all the outstanding subscriptions and cleans the subscription list.
int genaUnregisterDevice (UpnpDevice_Handle device_handle)
 Cleans the service table of the device.
int genaRenewSubscription (UpnpClient_Handle client_handle, const UpnpString *in_sid, int *TimeOut)
 Renews a SID.
int genaNotifyAll (UpnpDevice_Handle device_handle, char *UDN, char *servId, char **VarNames, char **VarValues, int var_count)
 Sends a notification to all the subscribed control points.
int genaNotifyAllExt (UpnpDevice_Handle device_handle, char *UDN, char *servId, IXML_Document *PropSet)
 Sends a notification to all the subscribed control points.
int genaInitNotify (UpnpDevice_Handle device_handle, char *UDN, char *servId, char **VarNames, char **VarValues, int var_count, const Upnp_SID sid)
 Sends the intial state table dump to newly subscribed control point.
int genaInitNotifyExt (UpnpDevice_Handle device_handle, char *UDN, char *servId, IXML_Document *PropSet, const Upnp_SID sid)
 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.
void error_respond (SOCKINFO *info, int error_code, http_message_t *hmsg)
 Sends an error message to the control point in the case of incorrect GENA requests.

Variables

ithread_mutex_t GlobalClientSubscribeMutex

Detailed Description


Define Documentation

#define SubscribeLock (  ) 
Value:
UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
                "Trying Subscribe Lock\n");  \
        ithread_mutex_lock(&GlobalClientSubscribeMutex); \
        UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
                "Subscribe Lock\n");

Locks the subscription.

Referenced by gena_process_notification_event(), and genaSubscribe().

#define SubscribeUnlock (  ) 
Value:
UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
                "Trying Subscribe UnLock\n"); \
        ithread_mutex_unlock(&GlobalClientSubscribeMutex); \
        UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, \
                "Subscribe UnLock\n");

Unlocks the subscription.

Referenced by gena_process_notification_event(), and genaSubscribe().

#define XML_VERSION   "<?xml version='1.0' encoding='ISO-8859-1' ?>\n"

XML version comment. Not used because it is not interopeable with other UPnP vendors.


Typedef Documentation

Structure to send NOTIFY message to all subscribed control points


Function Documentation

void error_respond ( SOCKINFO info,
int  error_code,
http_message_t hmsg 
)

Sends an error message to the control point in the case of incorrect GENA requests.

Returns:
UPNP_E_SUCCESS if successful, otherwise appropriate error code.
Parameters:
[in] info Structure containing information about the socket.
[in] error_code error code that will be in the GENA response.
[in] hmsg GENA request Packet.

Referenced by gena_process_notification_event(), gena_process_subscription_renewal_request(), gena_process_subscription_request(), gena_process_unsubscribe_request(), and respond_ok().

void genaCallback ( http_parser_t parser,
http_message_t request,
SOCKINFO info 
)

This is the callback function called by the miniserver to handle incoming GENA requests.

Returns:
UPNP_E_SUCCESS if successful, otherwise appropriate error code.
Parameters:
[in] parser represents the parse state of the request
[in] request HTTP message containing GENA request
[in,out] info Structure containing information about the socket

Referenced by UpnpInitPreamble().

int genaInitNotify ( UpnpDevice_Handle  device_handle,
char *  UDN,
char *  servId,
char **  VarNames,
char **  VarValues,
int  var_count,
const Upnp_SID  sid 
)

Sends the intial state table dump to newly subscribed control point.

Returns:
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.
Parameters:
[in] device_handle Device handle.
[in] UDN Device udn.
[in] servId Service ID.
[in] VarNames Array of variable names.
[in] VarValues Array of variable values.
[in] var_count Array size.
[in] sid Subscription ID.

References AllocGenaHeaders(), DOMString, free_notify_struct(), genaNotifyThread(), GeneratePropertySet(), GetHandleInfo(), gSendThreadPool, ixmlFreeDOMString(), Handle_Info::ServiceTable, and UpnpPrintf().

Referenced by UpnpAcceptSubscription().

int genaInitNotifyExt ( UpnpDevice_Handle  device_handle,
char *  UDN,
char *  servId,
IXML_Document PropSet,
const Upnp_SID  sid 
)

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.

Returns:
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.
Parameters:
[in] device_handle Device handle.
[in] UDN Device udn.
[in] servId Service ID.
[in] PropSet Document of the state table.
[in] sid subscription ID.

References AllocGenaHeaders(), DOMString, free_notify_struct(), genaNotifyThread(), GetHandleInfo(), gSendThreadPool, ixmlFreeDOMString(), ixmlPrintNode(), Handle_Info::ServiceTable, and UpnpPrintf().

Referenced by UpnpAcceptSubscriptionExt().

int genaNotifyAll ( UpnpDevice_Handle  device_handle,
char *  UDN,
char *  servId,
char **  VarNames,
char **  VarValues,
int  var_count 
)

Sends a notification to all the subscribed control points.

Returns:
int
Note:
This function is similar to the genaNotifyAllExt. The only difference is it takes event variable array instead of xml document.
Parameters:
[in] device_handle Device handle.
[in] UDN Device udn.
[in] servId Service ID.
[in] VarNames Array of varible names.
[in] VarValues Array of variable values.
[in] var_count Number of variables.

References AllocGenaHeaders(), DOMString, free_notify_struct(), genaNotifyThread(), GeneratePropertySet(), GetHandleInfo(), gSendThreadPool, ixmlFreeDOMString(), Handle_Info::ServiceTable, and UpnpPrintf().

Referenced by UpnpNotify().

int genaNotifyAllExt ( UpnpDevice_Handle  device_handle,
char *  UDN,
char *  servId,
IXML_Document PropSet 
)

Sends a notification to all the subscribed control points.

Returns:
int
Note:
This function is similar to the genaNotifyAll. the only difference is it takes the document instead of event variable array.
Parameters:
[in] device_handle Device handle.
[in] UDN Device udn.
[in] servId Service ID.
[in] PropSet XML document Event varible property set.

References AllocGenaHeaders(), DOMString, free_notify_struct(), genaNotifyThread(), GetHandleInfo(), gSendThreadPool, ixmlFreeDOMString(), ixmlPrintNode(), Handle_Info::ServiceTable, and UpnpPrintf().

Referenced by UpnpNotifyExt().

int genaRenewSubscription ( UpnpClient_Handle  client_handle,
const UpnpString in_sid,
int *  TimeOut 
)

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.

Returns:
UPNP_E_SUCCESS if service response is OK, otherwise the appropriate error code.
Parameters:
[in] client_handle Client handle.
[in] in_sid Subscription ID.
[in,out] TimeOut requested Duration, if -1, then "infinite". In the OUT case: actual Duration granted by Service, -1 for infinite.

References Handle_Info::ClientSubList, free_upnp_timeout(), gena_subscribe(), GetHandleInfo(), gTimerThread, ScheduleGenaAutoRenew(), TimerThreadRemove(), UPNP_E_SUCCESS, UpnpPrintf(), UpnpString_delete(), and UpnpString_new().

Referenced by GenaAutoRenewSubscription(), UpnpRenewSubscription(), and UpnpThreadDistribution().

int genaSubscribe ( UpnpClient_Handle  client_handle,
const UpnpString PublisherURL,
int *  TimeOut,
UpnpString out_sid 
)

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.

Returns:
UPNP_E_SUCCESS if service response is OK, otherwise returns the appropriate error code
Parameters:
[in] client_handle The client handle.
[in] PublisherURL Of the form: "http://134.134.156.80:4000/RedBulb/Event @param[in,out] TimeOut requested Duration: \li if -1, then "infinite".

  • in the OUT case: actual Duration granted by Service, -1 for infinite.
[out] out_sid sid of subscription, memory passed in by caller.

References Handle_Info::ClientSubList, gena_subscribe(), GetHandleInfo(), ScheduleGenaAutoRenew(), SubscribeLock, SubscribeUnlock, UPNP_E_SUCCESS, UpnpPrintf(), UpnpString_assign(), UpnpString_clear(), UpnpString_delete(), UpnpString_new(), and UpnpString_set_String().

Referenced by UpnpSubscribe(), and UpnpThreadDistribution().

int genaUnregisterClient ( UpnpClient_Handle  client_handle  ) 

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.
Parameters:
[in] client_handle Handle containing all the control point related information.

References Handle_Info::ClientSubList, gena_unsubscribe(), and GetHandleInfo().

Referenced by UpnpUnRegisterClient().

int genaUnregisterDevice ( UpnpDevice_Handle  device_handle  ) 

Cleans the service table of the device.

Returns:
UPNP_E_SUCCESS if successful, otherwise returns GENA_E_BAD_HANDLE

Cleans the service table of the device.

Returns:
UPNP_E_SUCCESS on success, GENA_E_BAD_HANDLE on failure.
Parameters:
[in] device_handle Device handle.

References GetHandleInfo(), Handle_Info::ServiceTable, and UpnpPrintf().

Referenced by UpnpUnRegisterRootDevice().

int genaUnSubscribe ( UpnpClient_Handle  client_handle,
const UpnpString in_sid 
)

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.

Returns:
UPNP_E_SUCCESS if service response is OK, otherwise returns the appropriate error code.
Parameters:
[in] client_handle UPnP client handle.
[in] in_sid The subscription ID.

References Handle_Info::ClientSubList, gena_unsubscribe(), and GetHandleInfo().

Referenced by UpnpThreadDistribution(), and UpnpUnSubscribe().


Variable Documentation

ithread_mutex_t GlobalClientSubscribeMutex

Mutex to synchronize the subscription handling at the client side.

Referenced by UpnpFinish(), and UpnpInitMutexes().