generic-library/libupnp
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

White spaces.

Browse Source 
git-svn-id: https://pupnp.svn.sourceforge.net/svnroot/pupnp/trunk@361 119443c7-1b9e-41f8-b6fc-b9c35fce742c
This commit is contained in:
Marcelo Roberto Jimenez 2008-05-03 21:49:43 +00:00
parent d2c34a15de
commit be2fa49891
1 changed files with 172 additions and 198 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

370
upnp/inc/upnp.h
View File

@ -540,13 +540,11 @@ enum UpnpOpenFileMode
/** Returned when a control point application registers with {\bf /** Returned when a control point application registers with {\bf
* UpnpRegisterClient}. Client handles can only be used with * UpnpRegisterClient}. Client handles can only be used with
* functions that operate with a client handle. */ * functions that operate with a client handle. */
typedef int UpnpClient_Handle; typedef int UpnpClient_Handle;
/** Returned when a device application registers with {\bf /** Returned when a device application registers with {\bf
* UpnpRegisterRootDevice} or {\bf UpnpRegisterRootDevice2}. Device handles * UpnpRegisterRootDevice} or {\bf UpnpRegisterRootDevice2}. Device handles
* can only be used with functions that operate with a device handle. */ * can only be used with functions that operate with a device handle. */
typedef int UpnpDevice_Handle; typedef int UpnpDevice_Handle;
/** @name UPnP_EventType /** @name UPnP_EventType
@ -555,124 +553,106 @@ typedef int UpnpDevice_Handle;
reason for the callback. The descriptions for each event reason for the callback. The descriptions for each event
type describe the contents of the {\bf Event} parameter. type describe the contents of the {\bf Event} parameter.
*/ */
enum Upnp_EventType_e { enum Upnp_EventType_e {
/*
* Control callbacks
*/
/* /** Received by a device when a control point issues a control
* Control callbacks * request. The {\bf Event} parameter contains a pointer to a {\bf
*/ * UpnpActionRequest} structure containing the action. The application
* stores the results of the action in this structure. */
UPNP_CONTROL_ACTION_REQUEST,
/** Received by a device when a control point issues a control /** A {\bf UpnpSendActionAsync} call completed. The {\bf Event}
* request. The {\bf Event} parameter contains a pointer to a {\bf * parameter contains a pointer to a {\bf UpnpActionComplete} structure
* UpnpActionRequest} structure containing the action. The application * with the results of the action. */
* stores the results of the action in this structure. */ UPNP_CONTROL_ACTION_COMPLETE,
UPNP_CONTROL_ACTION_REQUEST, /** Received by a device when a query for a single service variable
* arrives. The {\bf Event} parameter contains a pointer to a {\bf
* UpnpStateVarRequest} structure containing the name of the variable
* and value. */
UPNP_CONTROL_GET_VAR_REQUEST,
/** A {\bf UpnpSendActionAsync} call completed. The {\bf Event} /** A {\bf UpnpGetServiceVarStatus} call completed. The {\bf Event}
* parameter contains a pointer to a {\bf UpnpActionComplete} structure * parameter contains a pointer to a {\bf UpnpStateVarComplete} structure
* with the results of the action. */ * containing the value for the variable. */
UPNP_CONTROL_GET_VAR_COMPLETE,
UPNP_CONTROL_ACTION_COMPLETE, /*
* Discovery callbacks
*/
/** Received by a device when a query for a single service variable /** Received by a control point when a new device or service is available.
* arrives. The {\bf Event} parameter contains a pointer to a {\bf * The {\bf Event} parameter contains a pointer to a {\bf
* UpnpStateVarRequest} structure containing the name of the variable * UpnpDiscovery} structure with the information about the device
* and value. */ * or service. */
UPNP_DISCOVERY_ADVERTISEMENT_ALIVE,
UPNP_CONTROL_GET_VAR_REQUEST, /** Received by a control point when a device or service shuts down. The {\bf
* Event} parameter contains a pointer to a {\bf UpnpDiscovery}
* structure containing the information about the device or
* service. */
UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE,
/** A {\bf UpnpGetServiceVarStatus} call completed. The {\bf Event} /** Received by a control point when a matching device or service responds.
* parameter contains a pointer to a {\bf UpnpStateVarComplete} structure * The {\bf Event} parameter contains a pointer to a {\bf
* containing the value for the variable. */ * UpnpDiscovery} structure containing the information about
* the reply to the search request. */
UPNP_DISCOVERY_SEARCH_RESULT,
UPNP_CONTROL_GET_VAR_COMPLETE, /** Received by a control point when the search timeout expires. The
* SDK generates no more callbacks for this search after this
* event. The {\bf Event} parameter is {\tt NULL}. */
UPNP_DISCOVERY_SEARCH_TIMEOUT,
/* /*
* Discovery callbacks * Eventing callbacks
*/ */
/** Received by a control point when a new device or service is available. /** Received by a device when a subscription arrives.
* The {\bf Event} parameter contains a pointer to a {\bf * The {\bf Event} parameter contains a pointer to a {\bf
* UpnpDiscovery} structure with the information about the device * UpnpSubscriptionRequest} structure. At this point, the
* or service. */ * subscription has already been accepted. {\bf UpnpAcceptSubscription}
* needs to be called to confirm the subscription and transmit the
* initial state table. This can be done during this callback. The SDK
* generates no events for a subscription unless the device
* application calls {\bf UpnpAcceptSubscription}.
*/
UPNP_EVENT_SUBSCRIPTION_REQUEST,
UPNP_DISCOVERY_ADVERTISEMENT_ALIVE, /** Received by a control point when an event arrives. The {\bf
* Event} parameter contains a {\bf UpnpEvent} structure
* with the information about the event. */
UPNP_EVENT_RECEIVED,
/** Received by a control point when a device or service shuts down. The {\bf /** A {\bf UpnpRenewSubscriptionAsync} call completed. The status of
* Event} parameter contains a pointer to a {\bf UpnpDiscovery} * the renewal is in the {\bf Event} parameter as a {\bf
* structure containing the information about the device or * Upnp_Event_Subscription} structure. */
* service. */ UPNP_EVENT_RENEWAL_COMPLETE,
UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE, /** A {\bf UpnpSubscribeAsync} call completed. The status of the
* subscription is in the {\bf Event} parameter as a {\bf
* Upnp_Event_Subscription} structure. */
UPNP_EVENT_SUBSCRIBE_COMPLETE,
/** Received by a control point when a matching device or service responds. /** A {\bf UpnpUnSubscribeAsync} call completed. The status of the
* The {\bf Event} parameter contains a pointer to a {\bf * subscription is in the {\bf Event} parameter as a {\bf
* UpnpDiscovery} structure containing the information about * EventSubscribe} structure. */
* the reply to the search request. */ UPNP_EVENT_UNSUBSCRIBE_COMPLETE,
UPNP_DISCOVERY_SEARCH_RESULT, /** The auto-renewal of a client subscription failed.
* The {\bf Event} parameter is a {\bf EventSubscribe} structure
/** Received by a control point when the search timeout expires. The * with the error code set appropriately. The subscription is no longer
* SDK generates no more callbacks for this search after this * valid. */
* event. The {\bf Event} parameter is {\tt NULL}. */ UPNP_EVENT_AUTORENEWAL_FAILED,
UPNP_DISCOVERY_SEARCH_TIMEOUT,
/*
* Eventing callbacks
*/
/** Received by a device when a subscription arrives.
* The {\bf Event} parameter contains a pointer to a {\bf
* UpnpSubscriptionRequest} structure. At this point, the
* subscription has already been accepted. {\bf UpnpAcceptSubscription}
* needs to be called to confirm the subscription and transmit the
* initial state table. This can be done during this callback. The SDK
* generates no events for a subscription unless the device
* application calls {\bf UpnpAcceptSubscription}.
*/
UPNP_EVENT_SUBSCRIPTION_REQUEST,
/** Received by a control point when an event arrives. The {\bf
* Event} parameter contains a {\bf UpnpEvent} structure
* with the information about the event. */
UPNP_EVENT_RECEIVED,
/** A {\bf UpnpRenewSubscriptionAsync} call completed. The status of
* the renewal is in the {\bf Event} parameter as a {\bf
* Upnp_Event_Subscription} structure. */
UPNP_EVENT_RENEWAL_COMPLETE,
/** A {\bf UpnpSubscribeAsync} call completed. The status of the
* subscription is in the {\bf Event} parameter as a {\bf
* Upnp_Event_Subscription} structure. */
UPNP_EVENT_SUBSCRIBE_COMPLETE,
/** A {\bf UpnpUnSubscribeAsync} call completed. The status of the
* subscription is in the {\bf Event} parameter as a {\bf
* EventSubscribe} structure. */
UPNP_EVENT_UNSUBSCRIBE_COMPLETE,
/** The auto-renewal of a client subscription failed.
* The {\bf Event} parameter is a {\bf EventSubscribe} structure
* with the error code set appropriately. The subscription is no longer
* valid. */
UPNP_EVENT_AUTORENEWAL_FAILED,
/** A client subscription has expired. This will only occur
* if auto-renewal of subscriptions is disabled.
* The {\bf Event} parameter is a {\bf EventSubscribe}
* structure. The subscription is no longer valid. */
UPNP_EVENT_SUBSCRIPTION_EXPIRED
/** A client subscription has expired. This will only occur
* if auto-renewal of subscriptions is disabled.
* The {\bf Event} parameter is a {\bf EventSubscribe}
* structure. The subscription is no longer valid. */
UPNP_EVENT_SUBSCRIPTION_EXPIRED
}; };
typedef enum Upnp_EventType_e Upnp_EventType; typedef enum Upnp_EventType_e Upnp_EventType;
@ -681,7 +661,6 @@ typedef enum Upnp_EventType_e Upnp_EventType;
between a client and a device. The SID is a string representation of between a client and a device. The SID is a string representation of
a globally unique id (GUID) and should not be modified. a globally unique id (GUID) and should not be modified.
*/ */
typedef char Upnp_SID[44]; typedef char Upnp_SID[44];
/** @name Upnp_SType /** @name Upnp_SType
@ -692,21 +671,19 @@ typedef char Upnp_SID[44];
can control the scope of the search from all devices can control the scope of the search from all devices
to specific devices or services. to specific devices or services.
*/ */
enum Upnp_SType_e { enum Upnp_SType_e {
/** Search for all devices and services on the network. */ /** Search for all devices and services on the network. */
UPNP_S_ALL, UPNP_S_ALL,
/** Search for all root devices on the network. */ /** Search for all root devices on the network. */
UPNP_S_ROOT, UPNP_S_ROOT,
/** Search for a particular device type or a particular device /** Search for a particular device type or a particular device instance. */
instance. */ UPNP_S_DEVICE,
UPNP_S_DEVICE,
/** Search for a particular service type, possibly on a particular
/** Search for a particular service type, possibly on a particular * device type or device instance. */
* device type or device instance. */ UPNP_S_SERVICE
UPNP_S_SERVICE
}; };
typedef enum Upnp_SType_e Upnp_SType; typedef enum Upnp_SType_e Upnp_SType;
@ -734,7 +711,6 @@ typedef enum Upnp_DescType_e Upnp_DescType;
/* The type of handle returned by the web server for open requests. */ /* The type of handle returned by the web server for open requests. */
typedef void *UpnpWebFileHandle; typedef void *UpnpWebFileHandle;
/** The {\bf UpnpVirtualDirCallbacks} structure contains the pointers to /** The {\bf UpnpVirtualDirCallbacks} structure contains the pointers to
@ -743,98 +719,97 @@ typedef void *UpnpWebFileHandle;
*/ */
struct UpnpVirtualDirCallbacks struct UpnpVirtualDirCallbacks
{ {
/** Called by the web server to query information on a file. The callback /** Called by the web server to query information on a file. The callback
* should return 0 on success or -1 on an error. */ * should return 0 on success or -1 on an error. */
int (*get_info) ( int (*get_info) (
IN const char *filename, /** The name of the file to query. */ /** The name of the file to query. */
OUT UpnpFileInfo *info /** Pointer to a structure to store the IN const char *filename,
information on the file. */ /** Pointer to a structure to store the information on the file. */
); OUT UpnpFileInfo *info);
/** Called by the web server to open a file. The callback should return
* a valid handle if the file can be opened. Otherwise, it should return
* {\tt NULL} to signify an error. */
UpnpWebFileHandle (*open)(
IN const char *filename, /** The name of the file to open. */
IN enum UpnpOpenFileMode Mode /** The mode in which to open the file.
Valid values are {\tt UPNP_READ} or
{\tt UPNP_WRITE}. */
);
/** Called by the web server to perform a sequential read from an open /** Called by the web server to open a file. The callback should return
* file. The callback should copy {\bf buflen} bytes from the file into * a valid handle if the file can be opened. Otherwise, it should return
* the buffer. * {\tt NULL} to signify an error. */
* @return [int] An integer representing one of the following: UpnpWebFileHandle (*open)(
* \begin{itemize} /** The name of the file to open. */
* \item {\tt 0}: The file contains no more data (EOF). IN const char *filename,
* \item {\tt >0}: A successful read of the number of bytes in the /** The mode in which to open the file.
* return code. * Valid values are {\tt UPNP_READ} or {\tt UPNP_WRITE}. */
* \item {\tt <0}: An error occurred reading the file. IN enum UpnpOpenFileMode Mode);
* \end{itemzie}
*/
int (*read) (
IN UpnpWebFileHandle fileHnd, /** The handle of the file to read. */
OUT char *buf, /** The buffer in which to place the
data. */
IN size_t buflen /** The size of the buffer (i.e. the
number of bytes to read). */
);
/** Called by the web server to perform a sequential write to an open /** Called by the web server to perform a sequential read from an open
* file. The callback should write {\bf buflen} bytes into the file from * file. The callback should copy {\bf buflen} bytes from the file into
* the buffer. It should return the actual number of bytes written, * the buffer.
* which might be less than {\bf buflen} in the case of a write error. * @return [int] An integer representing one of the following:
*/ * \begin{itemize}
int (*write) ( * \item {\tt 0}: The file contains no more data (EOF).
IN UpnpWebFileHandle fileHnd, /** The handle of the file to write. */ * \item {\tt >0}: A successful read of the number of bytes in the
IN char *buf, /** The buffer with the bytes to write. */ * return code.
IN size_t buflen /** The number of bytes to write. */ * \item {\tt <0}: An error occurred reading the file.
); * \end{itemzie}
*/
int (*read) (
/** The handle of the file to read. */
IN UpnpWebFileHandle fileHnd,
/** The buffer in which to place the data. */
OUT char *buf,
/** The size of the buffer (i.e. the number of bytes to read). */
IN size_t buflen);
/** Called by the web server to move the file pointer, or offset, into /** Called by the web server to perform a sequential write to an open
* an open file. The {\bf origin} parameter determines where to start * file. The callback should write {\bf buflen} bytes into the file from
* moving the file pointer. A value of {\tt SEEK_CUR} moves the * the buffer. It should return the actual number of bytes written,
* file pointer relative to where it is. The {\bf offset} parameter can * which might be less than {\bf buflen} in the case of a write error.
* be either positive (move forward) or negative (move backward). */
* {\tt SEEK_END} moves relative to the end of the file. A positive int (*write) (
* {\bf offset} extends the file. A negative {\bf offset} moves backward /** The handle of the file to write. */
* in the file. Finally, {\tt SEEK_SET} moves to an absolute position in IN UpnpWebFileHandle fileHnd,
* the file. In this case, {\bf offset} must be positive. The callback /** The buffer with the bytes to write. */
* should return 0 on a successful seek or a non-zero value on an error. IN char *buf,
*/ /** The number of bytes to write. */
int (*seek) ( IN size_t buflen);
IN UpnpWebFileHandle fileHnd, /** The handle of the file to move the
file pointer. */
IN off_t offset, /** The number of bytes to move in the
file. Positive values move foward and
negative values move backward. Note
that this must be positive if the
{\bf origin} is {\tt SEEK_SET}. */
IN int origin /** The position to move relative to. It
can be {\tt SEEK_CUR} to move relative
to the current position,
{\tt SEEK_END} to move relative to
the end of the file, or {\tt
SEEK_SET} to specify an absolute
offset. */
);
/** Called by the web server to close a file opened via the {\bf open} /** Called by the web server to move the file pointer, or offset, into
* callback. It should return 0 on success, or a non-zero value on an * an open file. The {\bf origin} parameter determines where to start
* error. * moving the file pointer. A value of {\tt SEEK_CUR} moves the
*/ * file pointer relative to where it is. The {\bf offset} parameter can
int (*close) ( * be either positive (move forward) or negative (move backward).
IN UpnpWebFileHandle fileHnd /** The handle of the file to close. */ * {\tt SEEK_END} moves relative to the end of the file. A positive
); * {\bf offset} extends the file. A negative {\bf offset} moves backward
* in the file. Finally, {\tt SEEK_SET} moves to an absolute position in
* the file. In this case, {\bf offset} must be positive. The callback
* should return 0 on a successful seek or a non-zero value on an error.
*/
int (*seek) (
/** The handle of the file to move the file pointer. */
IN UpnpWebFileHandle fileHnd,
/** The number of bytes to move in the file. Positive values
* move foward and negative values move backward. Note that
* this must be positive if the {\bf origin} is {\tt SEEK_SET}. */
IN off_t offset,
/** The position to move relative to. It can be {\tt SEEK_CUR}
* to move relative to the current position, {\tt SEEK_END} to
* move relative to the end of the file, or {\tt SEEK_SET} to
* specify an absolute offset. */
IN int origin);
/** Called by the web server to close a file opened via the {\bf open}
* callback. It should return 0 on success, or a non-zero value on an
* error.
*/
int (*close) (
/** The handle of the file to close. */
IN UpnpWebFileHandle fileHnd);
}; };
typedef struct virtual_Dir_List typedef struct virtual_Dir_List
{ {
struct virtual_Dir_List *next; struct virtual_Dir_List *next;
char dirName[NAME_SIZE]; char dirName[NAME_SIZE];
} virtualDirList; } virtualDirList;
/** All callback functions share the same prototype, documented below. /** All callback functions share the same prototype, documented below.
* Note that any memory passed to the callback function * Note that any memory passed to the callback function
* is valid only during the callback and should be copied if it * is valid only during the callback and should be copied if it
@ -859,7 +834,6 @@ typedef struct virtual_Dir_List
* The return value of the callback is currently ignored. It may be used * The return value of the callback is currently ignored. It may be used
* in the future to communicate results back to the SDK. * in the future to communicate results back to the SDK.
*/ */
typedef int (*Upnp_FunPtr)(IN Upnp_EventType EventType, IN void *Event, IN void *Cookie); typedef int (*Upnp_FunPtr)(IN Upnp_EventType EventType, IN void *Event, IN void *Cookie);
/*! @} */ /* Constants, Structures, and Types */ /*! @} */ /* Constants, Structures, and Types */