gena.h File Reference
`#include "config.h"`
`#include <time.h>`
`#include "UpnpString.h"`
`#include "httpparser.h"`
`#include "ithread.h"`
`#include "sock.h"`
`#include "upnp.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

## Macros

#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

## Macro Definition Documentation

## SubscribeLock

#define SubscribeLock | ( |  | ) |

Value:
UpnpPrintf( \
UPNP_INFO, GENA, __FILE__, __LINE__, "Trying Subscribe Lock"); \
ithread_mutex_lock(&GlobalClientSubscribeMutex); \
UpnpPrintf(UPNP_INFO, GENA, __FILE__, __LINE__, "Subscribe Lock")
GlobalClientSubscribeMutex
ithread_mutex_t GlobalClientSubscribeMutex
Definition upnpapi.c:115
UpnpPrintf
void UpnpPrintf(Upnp_LogLevel DLevel, Dbg_Module Module, const char *DbgFileName, int DbgLineNo, const char *FmtStr,...)
Prints the debug statement either on the standard output or log file along with the information from ...
Definition upnpdebug.c:259

Locks the subscription.

## SubscribeUnlock

#define SubscribeUnlock | ( |  | ) |

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

Unlocks the subscription.

## XML_VERSION

#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

## notify_thread_struct

typedef struct NOTIFY_THREAD_STRUCT notify_thread_struct

Structure to send NOTIFY message to all subscribed control points

## Function Documentation

## error_respond()

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.

## genaCallback()

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

References gena_process_notification_event(), gena_process_subscription_renewal_request(), gena_process_subscription_request(), gena_process_unsubscribe_request(), http_message_t::method, and UpnpPrintf().

## genaInitNotify()

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 device_handle, DOMString, GeneratePropertySet(), and UpnpPrintf().

Referenced by UpnpAcceptSubscription().

## genaInitNotifyExt()

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 device_handle, DOMString, ixmlPrintNode(), UPNP_E_INVALID_PARAM, and UpnpPrintf().

Referenced by UpnpAcceptSubscriptionExt().

## genaNotifyAll()

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 device_handle, DOMString, GeneratePropertySet(), and UpnpPrintf().

Referenced by UpnpNotify().

## genaNotifyAllExt()

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 device_handle, DOMString, ixmlPrintNode(), UPNP_E_INVALID_PARAM, and UpnpPrintf().

Referenced by UpnpNotifyExt().

## genaRenewSubscription()

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, gena_subscribe(), GenlibClientSubscription_assign(), GenlibClientSubscription_delete(), GenlibClientSubscription_get_ActualSID(), GenlibClientSubscription_get_EventURL(), GenlibClientSubscription_get_RenewEventId(), GenlibClientSubscription_get_SID(), GenlibClientSubscription_new(), GenlibClientSubscription_set_ActualSID(), GenlibClientSubscription_set_RenewEventId(), GetHandleInfo(), gTimerThread, ScheduleGenaAutoRenew(), TimerThreadRemove(), UPNP_E_SUCCESS, UpnpPrintf(), UpnpString_delete(), and UpnpString_new().

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

## genaSubscribe()

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

  [in,out]

  TimeOut

  requested Duration:
  - 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(), GenlibClientSubscription_delete(), GenlibClientSubscription_new(), GenlibClientSubscription_set_ActualSID(), GenlibClientSubscription_set_EventURL(), GenlibClientSubscription_set_Next(), GenlibClientSubscription_set_RenewEventId(), GenlibClientSubscription_set_SID(), GetHandleInfo(), ScheduleGenaAutoRenew(), SubscribeLock, SubscribeUnlock, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, UpnpPrintf(), UpnpString_assign(), UpnpString_clear(), UpnpString_delete(), UpnpString_new(), and UpnpString_set_String().

Referenced by UpnpSubscribe(), and UpnpThreadDistribution().

## genaUnregisterClient()

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(), GenlibClientSubscription_assign(), GenlibClientSubscription_delete(), GenlibClientSubscription_get_ActualSID(), GenlibClientSubscription_get_EventURL(), GenlibClientSubscription_get_SID(), GenlibClientSubscription_new(), GetHandleInfo(), and UPNP_E_SUCCESS.

Referenced by UpnpUnRegisterClient().

## genaUnregisterDevice()

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 device_handle, GetHandleInfo(), Handle_Info::ServiceTable, UPNP_E_SUCCESS, and UpnpPrintf().

Referenced by UpnpUnRegisterRootDeviceLowPower().

## genaUnSubscribe()

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(), GenlibClientSubscription_assign(), GenlibClientSubscription_delete(), GenlibClientSubscription_get_ActualSID(), GenlibClientSubscription_get_EventURL(), GenlibClientSubscription_new(), and GetHandleInfo().

Referenced by UpnpThreadDistribution(), and UpnpUnSubscribe().