upnpapi.h File Reference
`#include "client_table.h"`
`#include "upnp.h"`
`#include "VirtualDir.h"`
Include dependency graph for upnpapi.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures

struct | Handle_Info
struct | UpnpNonblockParam

## Macros

#define | MAX_INTERFACES 256
#define | DEFAULT_INTERFACE 1
#define | DEV_LIMIT 200
#define | NUM_HANDLE 200
#define | DEFAULT_MX 5
#define | DEFAULT_MAXAGE 1800
#define | DEFAULT_SOAP_CONTENT_LENGTH 16000
#define | MAX_SOAP_CONTENT_LENGTH 32000
#define | UPNP_TIMEOUT 30
#define | HandleLock() HandleWriteLock()
#define | HandleWriteLock()
#define | HandleReadLock()
#define | HandleUnlock()
#define | E_HTTP_SYNTAX -6

## Enumerations

enum | Upnp_Handle_Type { HND_INVALID =-1, HND_CLIENT, HND_DEVICE }
enum | UpnpFunName { SUBSCRIBE, UNSUBSCRIBE, DK_NOTIFY, QUERY, ACTION, STATUS, DEVDESCRIPTION, SERVDESCRIPTION, MINI, RENEW }
enum | WebServerState { WEB_SERVER_DISABLED, WEB_SERVER_ENABLED }

## Functions

Upnp_Handle_Type | GetHandleInfo (int Hnd, struct Handle_Info **HndInfo)
| Get handle information. More...
Upnp_Handle_Type | GetClientHandleInfo (int *client_handle_out, struct Handle_Info **HndInfo)
| Get client handle info. More...
Upnp_Handle_Type | GetDeviceHandleInfo (const int AddressFamily, int *device_handle_out, struct Handle_Info **HndInfo)
| Retrieves the device handle and information of the first device of the address family spcified. More...
int | UpnpGetIfInfo (const char *IfName)
| Retrieve interface information and keep it in global variables. If NULL, we'll find the first suitable interface for operation. More...
void | InitHandleList ()
| Initialize handle table. More...
int | GetFreeHandle ()
| Get a free handle. More...
int | FreeHandle (int Handle)
| Free handle. More...
void | UpnpThreadDistribution (struct UpnpNonblockParam *Param)
| Schedule async functions in threadpool. More...
void | AutoAdvertise (void *input)
| This function is a timer thread scheduled by UpnpSendAdvertisement to the send advetisement again. More...
int | getlocalhostname (char *out, const int out_len)
| Get local IP address. More...
int | PrintHandleInfo (UpnpClient_Handle Hnd)
| Print handle info. More...

## Variables

size_t | g_maxContentLength
ithread_rwlock_t | GlobalHndRWLock
char | gIF_NAME [LINE_SIZE]
char | gIF_IPV4 [22]
char | gIF_IPV6 [65]
int | gIF_INDEX
unsigned short | LOCAL_PORT_V4
unsigned short | LOCAL_PORT_V6
Upnp_SID | gUpnpSdkNLSuuid
TimerThread | gTimerThread
ThreadPool | gRecvThreadPool
ThreadPool | gSendThreadPool
ThreadPool | gMiniServerThreadPool
virtualDirList * | pVirtualDirList
struct VirtualDirCallbacks | virtualDirCallback
WebServerState | bWebServerState

## Macro Definition Documentation

#define HandleReadLock | ( |  | ) |

Value:
UpnpPrintf(UPNP_INFO, API, __FILE__, __LINE__, "Trying a read lock\n"); \
ithread_rwlock_rdlock(&GlobalHndRWLock); \
UpnpPrintf(UPNP_INFO, API, __FILE__, __LINE__, "Read lock acquired\n");
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:148
GlobalHndRWLock
ithread_rwlock_t GlobalHndRWLock
Definition: upnpapi.c:111

#define HandleUnlock | ( |  | ) |

Value:
UpnpPrintf(UPNP_INFO, API,__FILE__, __LINE__, "Trying Unlock\n"); \
ithread_rwlock_unlock(&GlobalHndRWLock); \
UpnpPrintf(UPNP_INFO, API, __FILE__, __LINE__, "Unlocked rwlock\n");
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:148
GlobalHndRWLock
ithread_rwlock_t GlobalHndRWLock
Definition: upnpapi.c:111

#define HandleWriteLock | ( |  | ) |

Value:
UpnpPrintf(UPNP_INFO, API, __FILE__, __LINE__, "Trying a write lock\n"); \
ithread_rwlock_wrlock(&GlobalHndRWLock); \
UpnpPrintf(UPNP_INFO, API, __FILE__, __LINE__, "Write lock acquired\n");
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:148
GlobalHndRWLock
ithread_rwlock_t GlobalHndRWLock
Definition: upnpapi.c:111

## Function Documentation

void AutoAdvertise | ( | void * | input | ) |

This function is a timer thread scheduled by UpnpSendAdvertisement to the send advetisement again.

Parameters

  [in] | input | Information provided to the thread.

References free_upnp_timeout(), and UpnpSendAdvertisement().

Referenced by UpnpSendAdvertisement().

int FreeHandle | ( | int | Handle | ) |

Free handle.

Returns
  UPNP_E_SUCCESS if successful or UPNP_E_INVALID_HANDLE if not

Parameters

  [in] | Handle | Handle index.

References HandleTable, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, and UpnpPrintf().

Referenced by UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), UpnpRegisterRootDevice3(), UpnpUnRegisterClient(), and UpnpUnRegisterRootDevice().

Upnp_Handle_Type GetClientHandleInfo | ( | int * | client_handle_out,
|  | struct Handle_Info ** | HndInfo
| ) |  |

Get client handle info.

Note
  The logic around the use of this function should be revised.

Returns
  HND_CLIENT, HND_INVALID

Parameters

  [in] | client_handle_out | client handle pointer (key for the client handle structure).
  [out] | HndInfo | Client handle structure passed by this function.

References GetHandleInfo().

Referenced by gena_process_notification_event(), and UpnpFinish().

Upnp_Handle_Type GetDeviceHandleInfo | ( | const int | AddressFamily,
|  | int * | device_handle_out,
|  | struct Handle_Info ** | HndInfo
| ) |  |

Retrieves the device handle and information of the first device of the address family spcified.

Returns
  HND_DEVICE or HND_INVALID

Parameters

  [in] | AddressFamily | Address family.
  [out] | device_handle_out | Device handle pointer.
  [out] | HndInfo | Device handle structure passed by this function.

References GetHandleInfo(), UpnpSdkDeviceRegisteredV4, and UpnpSdkDeviceregisteredV6.

Referenced by gena_process_subscription_renewal_request(), gena_process_subscription_request(), gena_process_unsubscribe_request(), and UpnpFinish().

int GetFreeHandle | ( |  | ) |

Get a free handle.

Returns
  On success, an integer greater than zero or UPNP_E_OUTOF_HANDLE on failure.

References HandleTable, and UPNP_E_OUTOF_HANDLE.

Referenced by UpnpRegisterClient(), UpnpRegisterRootDevice(), UpnpRegisterRootDevice2(), and UpnpRegisterRootDevice3().

Upnp_Handle_Type GetHandleInfo | ( | int | Hnd,
|  | struct Handle_Info ** | HndInfo
| ) |  |

Get handle information.

Returns
  HND_DEVICE, UPNP_E_INVALID_HANDLE

Parameters

  Hnd | handle pointer (key for the client handle structure).
  HndInfo | handle structure passed by this function.

References HandleTable, UPNP_E_INVALID_HANDLE, and UpnpPrintf().

Referenced by GenaAutoRenewSubscription(), genaInitNotify(), genaInitNotifyExt(), genaNotifyAll(), genaNotifyAllExt(), genaNotifyThread(), genaRenewSubscription(), genaSubscribe(), genaUnregisterClient(), genaUnregisterDevice(), genaUnSubscribe(), GetClientHandleInfo(), GetDeviceHandleInfo(), UpnpAcceptSubscription(), UpnpAcceptSubscriptionExt(), UpnpGetServiceVarStatus(), UpnpGetServiceVarStatusAsync(), UpnpNotify(), UpnpNotifyExt(), UpnpRenewSubscription(), UpnpRenewSubscriptionAsync(), UpnpSearchAsync(), UpnpSendAction(), UpnpSendActionAsync(), UpnpSendActionEx(), UpnpSendActionExAsync(), UpnpSendAdvertisement(), UpnpSetContentLength(), UpnpSetMaxSubscriptions(), UpnpSetMaxSubscriptionTimeOut(), UpnpSubscribe(), UpnpSubscribeAsync(), UpnpUnRegisterClient(), UpnpUnRegisterRootDevice(), UpnpUnSubscribe(), and UpnpUnSubscribeAsync().

int getlocalhostname | ( | char * | out,
|  | const int | out_len
| ) |  |

Get local IP address.

Gets the ip address for the DEFAULT_INTERFACE interface which is up and not a loopback. Assumes at most MAX_INTERFACES interfaces

Returns
  UPNP_E_SUCCESS if successful or UPNP_E_INIT.

Parameters

  [out] | out | IP address of the interface.
  [in] | out_len | Length of the output buffer.

References UPNP_E_INIT, UPNP_E_SUCCESS, and UpnpPrintf().

Referenced by UpnpInit().

void InitHandleList | ( |  | ) |

Initialize handle table.

int PrintHandleInfo | ( | UpnpClient_Handle | Hnd | ) |

Print handle info.

Returns
  UPNP_E_SUCCESS if successful, otherwise returns appropriate error.

Parameters

  [in] | Hnd | Handle index.

References Handle_Info::DescURL, HandleTable, Handle_Info::HType, UPNP_E_INVALID_HANDLE, UPNP_E_SUCCESS, and UpnpPrintf().

int UpnpGetIfInfo | ( | const char * | IfName | ) |

Retrieve interface information and keep it in global variables. If NULL, we'll find the first suitable interface for operation.

The interface must fulfill these requirements:

- Be UP.
- Not be LOOPBACK.
- Support MULTICAST.
- Have a valid IPv4 or IPv6 address.

We'll retrieve the following information from the interface:

- gIF_NAME -> Interface name (by input or found).
- gIF_IPV4 -> IPv4 address (if any).
- gIF_IPV6 -> IPv6 address (if any).
- gIF_INDEX -> Interface index number.

Returns
  UPNP_E_SUCCESS on success.

Parameters

  [in] | IfName | Interface name (can be NULL).

References gIF_INDEX, gIF_IPV4, gIF_IPV6, gIF_NAME, UPNP_E_INIT, UPNP_E_INVALID_INTERFACE, UPNP_E_OUTOF_MEMORY, UPNP_E_SUCCESS, and UpnpPrintf().

Referenced by UpnpInit2().

void UpnpThreadDistribution | ( | struct UpnpNonblockParam * | Param | ) |

Schedule async functions in threadpool.

References DOMString, genaRenewSubscription(), genaSubscribe(), genaUnSubscribe(), UPNP_CONTROL_ACTION_COMPLETE, UPNP_CONTROL_GET_VAR_COMPLETE, UPNP_EVENT_RENEWAL_COMPLETE, UPNP_EVENT_SUBSCRIBE_COMPLETE, UPNP_EVENT_UNSUBSCRIBE_COMPLETE, UpnpActionComplete_delete(), UpnpActionComplete_new(), UpnpActionComplete_set_ActionRequest(), UpnpActionComplete_set_ActionResult(), UpnpActionComplete_set_ErrCode(), UpnpActionComplete_strcpy_CtrlUrl(), UpnpEventSubscribe_delete(), UpnpEventSubscribe_get_PublisherUrl(), UpnpEventSubscribe_get_SID(), UpnpEventSubscribe_new(), UpnpPrintf(), UpnpStateVarComplete_delete(), and UpnpStateVarComplete_new().

Referenced by UpnpGetServiceVarStatusAsync(), UpnpRenewSubscriptionAsync(), UpnpSendActionAsync(), UpnpSendActionExAsync(), UpnpSubscribeAsync(), and UpnpUnSubscribeAsync().

## Variable Documentation

WebServerState bWebServerState

Flag to indicate the state of web server

Referenced by UpnpEnableWebserver(), and UpnpIsWebserverEnabled().

size_t g_maxContentLength

Maximum content-length (in bytes) that the SDK will process on an incoming packet. Content-Length exceeding this size will be not processed and error 413 (HTTP Error Code) will be returned to the remote end point.

Referenced by UpnpSetContentLength(), and UpnpSetMaxContentLength().

int gIF_INDEX

Contains interface index. (extern'ed in upnp.h)

Referenced by parse_hostport(), and UpnpGetIfInfo().

char gIF_IPV4[22]

INET_ADDRSTRLEN.

Static buffer to contain interface IPv4 address. (extern'ed in upnp.h)

Referenced by gena_subscribe(), UpnpGetIfInfo(), UpnpGetServerIpAddress(), and UpnpInit().

char gIF_IPV6[65]

INET6_ADDRSTRLEN.

Static buffer to contain interface IPv6 address. (extern'ed in upnp.h)

Referenced by gena_subscribe(), UpnpGetIfInfo(), and UpnpGetServerIp6Address().

char gIF_NAME[LINE_SIZE]

Static buffer to contain interface name. (extern'ed in upnp.h)

Referenced by UpnpGetIfInfo().

ithread_rwlock_t GlobalHndRWLock

rwlock to synchronize handles (root device or control point handle).

Referenced by UpnpFinish(), and UpnpInitMutexes().

ThreadPool gMiniServerThreadPool

Mini server thread pool.

Referenced by StartMiniServer().

ThreadPool gRecvThreadPool

Receive thread pool.

ThreadPool gSendThreadPool

Send thread pool.

Referenced by genaInitNotify(), genaInitNotifyExt(), genaNotifyAll(), genaNotifyAllExt(), and genaNotifyThread().

TimerThread gTimerThread

Global timer thread.

Referenced by free_client_subscription(), genaRenewSubscription(), and ScheduleGenaAutoRenew().

Upnp_SID gUpnpSdkNLSuuid

NLS uuid.

Global variable used in discovery notifications.

Referenced by UpnpInitPreamble().

unsigned short LOCAL_PORT_V4

local IPv4 port for the mini-server

Referenced by gena_subscribe(), UpnpGetServerPort(), UpnpInit(), and UpnpInitStartServers().

unsigned short LOCAL_PORT_V6

local IPv6 port for the mini-server

Referenced by gena_subscribe(), UpnpGetServerPort6(), and UpnpInitStartServers().

virtualDirList* pVirtualDirList

Pointer to the virtual directory list.

Referenced by UpnpAddVirtualDir(), UpnpRemoveAllVirtualDirs(), and UpnpRemoveVirtualDir().

struct VirtualDirCallbacks virtualDirCallback

This structure is for virtual directory callbacks

Referenced by UpnpVirtualDir_set_CloseCallback(), UpnpVirtualDir_set_GetInfoCallback(), UpnpVirtualDir_set_OpenCallback(), UpnpVirtualDir_set_ReadCallback(), UpnpVirtualDir_set_SeekCallback(), and UpnpVirtualDir_set_WriteCallback().