pupnp (libupnp) snapshot from SourceForge: git clone git://pupnp.git.sourceforge...
[igd2-for-linux:pandonghui1211s-igd2-for-linux.git] / pupnp_branch-1.6.x / upnp / inc / upnp.h
1 /*******************************************************************************
2  *
3  * Copyright (c) 2000-2003 Intel Corporation 
4  * All rights reserved. 
5  *
6  * Redistribution and use in source and binary forms, with or without 
7  * modification, are permitted provided that the following conditions are met: 
8  *
9  * * Redistributions of source code must retain the above copyright notice, 
10  * this list of conditions and the following disclaimer. 
11  * * Redistributions in binary form must reproduce the above copyright notice, 
12  * this list of conditions and the following disclaimer in the documentation 
13  * and/or other materials provided with the distribution. 
14  * * Neither name of Intel Corporation nor the names of its contributors 
15  * may be used to endorse or promote products derived from this software 
16  * without specific prior written permission.
17  * 
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR 
22  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
23  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 
24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 
25  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY 
26  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
27  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 
28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  *
30  ******************************************************************************/
31
32
33 #ifndef UPNP_H
34 #define UPNP_H
35
36
37 /*!
38  * \file
39  *
40  * \defgroup UPnPAPI UPnP API
41  * 
42  * @{
43  */
44
45
46 #include "ixml.h"
47 #include "upnpconfig.h"
48 #include "UpnpGlobal.h"
49 #include "UpnpInet.h"
50
51
52 /*
53  * \todo Document the exact reason of these include files and solve this
54  * include mess in an include file like UpnpTime.h
55  */
56 #ifdef WIN32
57         #include <time.h>
58 #elif (defined(BSD) && BSD >= 199306)
59         #include <time.h>
60 #else
61         /* Other systems ??? */
62 #endif
63
64
65 #ifdef WIN32
66         /* Do not #include <sys/param.h> */
67 #else
68         #include <sys/param.h>
69 #endif
70
71
72 #ifdef WIN32
73         #include <iphlpapi.h>
74 #else
75         #define SOCKET int
76         #define INVALID_SOCKET (SOCKET)(~0)
77 #endif
78
79
80 #ifdef WIN32
81         #define UpnpCloseSocket closesocket
82         #define fseeko fseek
83 #else
84         #define UpnpCloseSocket close
85 #endif
86
87
88 #define NUM_HANDLE 200
89 #define LINE_SIZE  180
90 #define NAME_SIZE  256
91 #define MNFT_NAME_SIZE  64
92 #define MODL_NAME_SIZE  32
93 #define SERL_NUMR_SIZE  64
94 #define MODL_DESC_SIZE  64
95 #define UPNP_INFINITE           -1
96 #define UPNP_USING_CHUNKED      -3
97 #define UPNP_UNTIL_CLOSE        -4
98
99
100 /*!
101  * \name Error codes 
102  *
103  * The functions in the SDK API can return a variety of error 
104  * codes to describe problems encountered during execution.  This section 
105  * lists the error codes and provides a brief description of what each error 
106  * code means.  Refer to the documentation for each function for a 
107  * description of what an error code means in that context.
108  *
109  * @{
110  */
111
112 /*!
113  * \brief The operation completed successfully.
114  *
115  * For asynchronous functions, this only means that the packet generated by 
116  * the operation was successfully transmitted on the network.  The result of 
117  * the entire operation comes as part of the callback for that operation.
118  */
119 #define UPNP_E_SUCCESS                  0
120
121 /*!
122  * \brief The handle passed to a function is not a recognized as a valid handle.
123  */
124 #define UPNP_E_INVALID_HANDLE           -100
125
126 /*!
127  * \brief One or more of the parameters passed to the function is not valid.
128  *
129  * Refer to the documentation for each function for more information on the
130  * valid ranges of the parameters.
131  */
132 #define UPNP_E_INVALID_PARAM            -101
133
134 /*!
135  * \brief The SDK does not have any more space for additional handles.
136  *
137  * The SDK allocates space for only a few handles in order to conserve memory.
138  */
139 #define UPNP_E_OUTOF_HANDLE             -102
140
141 #define UPNP_E_OUTOF_CONTEXT            -103
142
143 /*!
144  * \brief Not enough resources are currently available to complete the operation.
145  *
146  * Most operations require some free memory in order to complete their work.
147  */
148 #define UPNP_E_OUTOF_MEMORY             -104
149
150 /*!
151  * \brief The SDK has already been initialized.
152  *
153  * The SDK needs to be initialied only once per process. Any additional
154  * initialization attempts simply return this error with no other ill effects.
155  */
156 #define UPNP_E_INIT                     -105
157
158 #define UPNP_E_BUFFER_TOO_SMALL         -106
159
160 /*!
161  * \brief The description document passed to \b UpnpRegisterRootDevice or
162  * \b UpnpRegisterRootDevice2 is invalid.
163  */
164 #define UPNP_E_INVALID_DESC             -107
165
166 /*!
167  * \brief An URL passed into the function is invalid.
168  *
169  * The actual cause is function specific, but in general, the URL itself
170  * might be malformed (e.g. have invalid characters in it) or the host might
171  * be unreachable.
172  */
173 #define UPNP_E_INVALID_URL              -108
174
175 #define UPNP_E_INVALID_SID              -109
176
177 #define UPNP_E_INVALID_DEVICE           -110
178
179 /*!
180  * \brief The device ID/service ID pair does not refer to a valid service.
181  *
182  * Returned only by \b UpnpNotify, \b UpnpNotifyExt, \b UpnpAcceptSubscription,
183  * and \b UpnpAcceptSubscriptionExt.
184  */
185 #define UPNP_E_INVALID_SERVICE          -111
186
187 /*!
188  * \brief The response received from the remote side of a connection is not correct
189  * for the protocol.
190  *
191  * This applies to the GENA, SOAP, and HTTP protocols.
192  */
193 #define UPNP_E_BAD_RESPONSE             -113
194
195 #define UPNP_E_BAD_REQUEST              -114
196
197 /*!
198  * \brief The SOAP action message is invalid.
199  *
200  * This can be because the DOM document passed to the function was malformed or
201  * the action message is not correct for the given action.
202  */
203 #define UPNP_E_INVALID_ACTION           -115
204
205 /*!
206  * \brief \b UpnpInit has not been called, or \b UpnpFinish has already been called.
207  *
208  * None of the API functions operate until \b UpnpInit successfully completes.
209  */
210 #define UPNP_E_FINISH                   -116
211
212 /*!
213  * \brief \b UpnpInit cannot complete.  
214  *
215  * The typical reason is failure to allocate sufficient resources.
216  */
217 #define UPNP_E_INIT_FAILED              -117
218
219 /*!
220  * \brief The URL passed into a function is too long.
221  *
222  * The SDK limits URLs to 180 characters in length.  
223  */
224 #define UPNP_E_URL_TOO_BIG              -118
225
226 /*!
227  * \brief The HTTP message contains invalid message headers.
228  *
229  * The error always refers to the HTTP message header received from the remote
230  * host.  The main areas where this occurs are in SOAP control messages (e.g.
231  * \b UpnpSendAction), GENA subscription message (e.g. \b UpnpSubscribe),
232  * GENA event notifications (e.g. \b UpnpNotify), and HTTP transfers (e.g.
233  * \b UpnpDownloadXmlDoc).
234  */
235 #define UPNP_E_BAD_HTTPMSG              -119
236
237 /*!
238  * \brief A client or a device is already registered.
239  *
240  * The SDK currently has a limit of one registered client and one registered
241  * device per process.
242  */
243 #define UPNP_E_ALREADY_REGISTERED       -120
244
245 /*!
246  * \brief The interface provided to \b UpnpInit2 is unknown or does not have a valid
247  * IPv4 or IPv6 address configured.
248  */
249 #define UPNP_E_INVALID_INTERFACE        -121
250
251 /*!
252  * \brief A network error occurred.
253  *
254  * It is the generic error code for network problems that are not covered under
255  * one of the more specific error codes.  The typical meaning is the SDK failed
256  * to read the local IP address or had problems configuring one of the sockets.
257  */
258 #define UPNP_E_NETWORK_ERROR            -200
259
260 /*!
261  * \brief An error happened while writing to a socket.
262  *
263  * This occurs in any function that makes network connections, such as discovery
264  * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g. 
265  * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g.
266  * \b UpnpDownloadXmlDoc).
267  */
268 #define UPNP_E_SOCKET_WRITE             -201
269
270 /*!
271  * \brief An error happened while reading from a socket.
272  *
273  * This occurs in any function that makes network connections, such as discovery
274  * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g.
275  * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g.
276  * \b UpnpDownloadXmlDoc).
277  */
278 #define UPNP_E_SOCKET_READ              -202
279
280 /*!
281  * \brief The SDK had a problem binding a socket to a network interface.
282  *
283  * This occurs in any function that makes network connections, such as discovery
284  * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g.
285  * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g. 
286  * \b UpnpDownloadXmlDoc).
287  */
288 #define UPNP_E_SOCKET_BIND              -203
289
290 /*!
291  * \brief The SDK had a problem connecting to a remote host.
292  *
293  * This occurs in any function that makes network connections, such as discovery
294  * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g.
295  * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g. 
296  * \b UpnpDownloadXmlDoc).
297  */
298 #define UPNP_E_SOCKET_CONNECT           -204
299
300 /*!
301  * \brief The SDK cannot create any more sockets.
302  *
303  * This occurs in any function that makes network connections, such as discovery
304  * (e.g. \b UpnpSearchAsync or \b UpnpSendAdvertisement), control (e.g.
305  * \b UpnpSendAction), eventing (e.g. \b UpnpNotify), and HTTP functions (e.g. 
306  * \b UpnpDownloadXmlDoc).
307  */
308 #define UPNP_E_OUTOF_SOCKET             -205
309
310 /*!
311  * \brief The SDK had a problem setting the socket to listen for incoming
312  * connections.
313  *
314  * This error only happens during initialization (i.e. \b UpnpInit).
315  */
316 #define UPNP_E_LISTEN                   -206
317
318 /*!
319  * \brief Too much time elapsed before the required number of bytes were sent
320  * or received over a socket.
321  *
322  * This error can be returned by any function that performs network operations.
323  */
324 #define UPNP_E_TIMEDOUT                 -207
325
326 /*!
327  * \brief Generic socket error code for conditions not covered by other error
328  * codes.
329  *
330  * This error can be returned by any function that performs network operations.
331  */
332 #define UPNP_E_SOCKET_ERROR             -208
333
334 #define UPNP_E_FILE_WRITE_ERROR         -209
335
336 /*! \brief The operation was canceled.
337  *
338  * This error can be returned by any function that allows for external cancelation.
339  */
340 #define UPNP_E_CANCELED                 -210
341
342 #define UPNP_E_EVENT_PROTOCOL           -300
343
344 /*!
345  * \brief A subscription request was rejected from the remote side.  
346  */
347 #define UPNP_E_SUBSCRIBE_UNACCEPTED     -301
348
349 /*!
350  * \brief An unsubscribe request was rejected from the remote side.
351  */
352 #define UPNP_E_UNSUBSCRIBE_UNACCEPTED   -302
353
354 /*!
355  * \brief The remote host did not accept the notify sent from the local device.
356  */
357 #define UPNP_E_NOTIFY_UNACCEPTED        -303
358
359 /*!
360  * \brief One or more of the parameters passed to a function is invalid.
361  *
362  * Refer to the individual function descriptions for the acceptable ranges for
363  * parameters.
364  */
365 #define UPNP_E_INVALID_ARGUMENT         -501
366
367 /*!
368  * \brief The filename passed to one of the device registration functions was
369  * not found or was not accessible.
370  */
371 #define UPNP_E_FILE_NOT_FOUND           -502
372
373 /*!
374  * \brief An error happened while reading a file.
375  */
376 #define UPNP_E_FILE_READ_ERROR          -503
377
378 /*!
379  * \brief The file name of the description document passed to
380  * \b UpnpRegisterRootDevice2 does not end in ".xml".
381  */
382 #define UPNP_E_EXT_NOT_XML              -504
383
384 #define UPNP_E_NO_WEB_SERVER            -505
385 #define UPNP_E_OUTOF_BOUNDS             -506
386
387 /*!
388  * \brief The response to a SOAP request did not contain the required XML
389  * constructs.  
390  */
391 #define UPNP_E_NOT_FOUND                -507
392
393 /*!
394  * \brief Generic error code for internal conditions not covered by other
395  * error codes.
396  */
397 #define UPNP_E_INTERNAL_ERROR           -911
398
399 /* SOAP-related error codes */
400 #define UPNP_SOAP_E_INVALID_ACTION      401
401 #define UPNP_SOAP_E_INVALID_ARGS        402
402 #define UPNP_SOAP_E_OUT_OF_SYNC         403
403 #define UPNP_SOAP_E_INVALID_VAR         404
404 #define UPNP_SOAP_E_ACTION_FAILED       501
405
406 /* @} ErrorCodes */
407
408 #ifndef OUT
409 #define OUT
410 #endif
411
412 #ifndef IN
413 #define IN
414 #endif
415
416 #ifndef INOUT
417 #define INOUT
418 #endif
419
420
421
422 /*!
423  * \name Constants and Types
424  *
425  * @{
426  */
427
428 enum UpnpOpenFileMode
429 {
430         UPNP_READ,
431         UPNP_WRITE
432 };
433
434 /*!
435  * \brief Returned when a control point application registers with
436  * \b UpnpRegisterClient.
437  *
438  * Client handles can only be used with functions that operate with a client
439  * handle.
440  */
441 typedef int  UpnpClient_Handle;
442
443 /*!
444  * \brief Returned when a device application registers with
445  * \b UpnpRegisterRootDevice or \b UpnpRegisterRootDevice2.
446  *
447  * Device handles can only be used with functions that operate with a device
448  * handle.
449  */
450 typedef int  UpnpDevice_Handle;
451
452 /*!
453  * \brief The reason code for an event callback.
454  *
455  * The \b Event parameter will be different depending on the reason for the
456  * callback. The descriptions for each event type describe the contents of the
457  * \b Event parameter.
458  */
459 enum Upnp_EventType_e {
460         /*
461          * Control callbacks
462          */
463
464         /*! Received by a device when a control point issues a control
465          * request.  The \b Event parameter contains a pointer to a \b
466          * UpnpActionRequest structure containing the action.  The application
467          * stores the results of the action in this structure. */
468         UPNP_CONTROL_ACTION_REQUEST,
469
470         /*! A \b UpnpSendActionAsync call completed. The \b Event
471          * parameter contains a pointer to a \b UpnpActionComplete structure
472          * with the results of the action.  */
473         UPNP_CONTROL_ACTION_COMPLETE,
474
475         /*! Received by a device when a query for a single service variable
476          * arrives.  The \b Event parameter contains a pointer to a \b
477          * UpnpStateVarRequest structure containing the name of the variable
478          * and value.  */
479         UPNP_CONTROL_GET_VAR_REQUEST,
480
481         /*! A \b UpnpGetServiceVarStatus call completed. The \b Event
482          * parameter contains a pointer to a \b UpnpStateVarComplete structure
483          * containing the value for the variable.  */
484         UPNP_CONTROL_GET_VAR_COMPLETE,
485
486         /*
487          * Discovery callbacks
488          */
489
490         /*! Received by a control point when a new device or service is available.  
491          * The \b Event parameter contains a pointer to a \b
492          * UpnpDiscovery structure with the information about the device
493          * or service.  */
494         UPNP_DISCOVERY_ADVERTISEMENT_ALIVE,
495
496         /*! Received by a control point when a device or service shuts down. The \b
497          * Event parameter contains a pointer to a \b UpnpDiscovery
498          * structure containing the information about the device or
499          * service.  */
500         UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE,
501
502         /*! Received by a control point when a matching device or service responds.
503          * The \b Event parameter contains a pointer to a \b
504          * UpnpDiscovery structure containing the information about
505          * the reply to the search request.  */
506         UPNP_DISCOVERY_SEARCH_RESULT,
507
508         /*! Received by a control point when the search timeout expires.  The
509          * SDK generates no more callbacks for this search after this 
510          * event.  The \b Event parameter is \c NULL.  */
511         UPNP_DISCOVERY_SEARCH_TIMEOUT,
512
513         /*
514          * Eventing callbacks
515          */
516
517         /*! Received by a device when a subscription arrives.
518          * The \b Event parameter contains a pointer to a \b
519          * UpnpSubscriptionRequest structure.  At this point, the
520          * subscription has already been accepted.  \b UpnpAcceptSubscription
521          * needs to be called to confirm the subscription and transmit the
522          * initial state table.  This can be done during this callback.  The SDK
523          * generates no events for a subscription unless the device 
524          * application calls \b UpnpAcceptSubscription.
525          */
526         UPNP_EVENT_SUBSCRIPTION_REQUEST,
527
528         /*! Received by a control point when an event arrives. The \b
529          * Event parameter contains a \b UpnpEvent structure
530          * with the information about the event.  */
531         UPNP_EVENT_RECEIVED,
532
533         /*! A \b UpnpRenewSubscriptionAsync call completed. The status of
534          * the renewal is in the \b Event parameter as a \b
535          * Upnp_Event_Subscription structure.  */
536         UPNP_EVENT_RENEWAL_COMPLETE,
537
538         /*! A \b UpnpSubscribeAsync call completed. The status of the
539          * subscription is in the \b Event parameter as a \b
540          * Upnp_Event_Subscription structure.  */
541         UPNP_EVENT_SUBSCRIBE_COMPLETE,
542
543         /*! A \b UpnpUnSubscribeAsync call completed. The status of the
544          * subscription is in the \b Event parameter as a \b
545          * UpnpEventSubscribe structure.  */
546         UPNP_EVENT_UNSUBSCRIBE_COMPLETE,
547
548         /*! The auto-renewal of a client subscription failed.   
549          * The \b Event parameter is a \b UpnpEventSubscribe structure 
550          * with the error code set appropriately. The subscription is no longer 
551          * valid. */
552         UPNP_EVENT_AUTORENEWAL_FAILED,
553
554         /*! A client subscription has expired. This will only occur 
555          * if auto-renewal of subscriptions is disabled.
556          * The \b Event parameter is a \b UpnpEventSubscribe
557          * structure. The subscription is no longer valid. */
558         UPNP_EVENT_SUBSCRIPTION_EXPIRED
559 };
560
561 typedef enum Upnp_EventType_e Upnp_EventType;
562
563 /*!
564  * \brief Holds the subscription identifier for a subscription between a
565  * client and a device.
566  *
567  * The SID is a string representation of a globally unique id (GUID) and should
568  * not be modified.
569  */
570 typedef char Upnp_SID[44];
571
572 /*!
573  * \brief Represents the different types of searches that can be performed
574  * using the SDK for UPnP Devices API.
575  *
576  * By specifying these different values to \b UpnpSearchAsync, the control
577  * point application can control the scope of the search from all devices
578  * to specific devices or services.
579  */
580 enum Upnp_SType_e {
581         /*! Search for all devices and services on the network. */
582         UPNP_S_ALL,    
583
584         /*! Search for all root devices on the network. */
585         UPNP_S_ROOT,   
586
587         /*! Search for a particular device type or a particular device instance. */
588         UPNP_S_DEVICE, 
589
590         /*! Search for a particular service type, possibly on a particular
591          *  device type or device instance.  */
592         UPNP_S_SERVICE 
593 };
594
595 typedef enum Upnp_SType_e Upnp_SType;
596
597 /*!
598  * \brief Specifies the type of description in \b UpnpRegisterRootDevice2.
599  *
600  * These values control how \b UpnpRegisterRootDevice2 interprets the
601  * \b description parameter.
602  */
603 enum Upnp_DescType_e { 
604         /*! The description is the URL to the description document. */
605         UPNPREG_URL_DESC, 
606         
607         /*! The description is a file name on the local file system 
608             containing the description of the device. */
609         UPNPREG_FILENAME_DESC,
610     
611         /*! The description is a pointer to a character array containing 
612             the XML description document. */
613         UPNPREG_BUF_DESC 
614 };
615
616 typedef enum Upnp_DescType_e Upnp_DescType;
617
618 /** Returned as part of a {\bf UPNP_CONTROL_ACTION_COMPLETE} callback.  */
619
620 struct Upnp_Action_Request
621 {
622   /** The result of the operation. */
623   int ErrCode;
624
625   /** The socket number of the connection to the requestor. */
626   int Socket;
627
628   /** The error string in case of error. */
629   char ErrStr[LINE_SIZE];
630
631  /** The Action Name. */
632   char ActionName[NAME_SIZE];
633
634   /** The unique device ID. */
635   char DevUDN[NAME_SIZE];
636
637   /** The service ID. */
638   char ServiceID[NAME_SIZE];
639
640   /** The DOM document describing the action. */
641   IXML_Document *ActionRequest;
642
643   /** The DOM document describing the result of the action. */
644   IXML_Document *ActionResult;
645
646   /** IP address of the control point requesting this action. */
647   struct in_addr CtrlPtIPAddr;
648
649   /** The DOM document containing the information from the
650       the SOAP header. */
651   IXML_Document *SoapHeader;
652 };
653
654 struct Upnp_Action_Complete
655 {
656   /** The result of the operation. */
657   int ErrCode;
658
659   /** The control URL for service. */
660   char CtrlUrl[NAME_SIZE];
661
662   /** The DOM document describing the action. */
663   IXML_Document *ActionRequest;
664
665   /** The DOM document describing the result of the action. */
666   IXML_Document *ActionResult;
667
668 };
669
670 /** Represents the request for current value of a state variable in a service
671  *  state table.  */
672
673 struct Upnp_State_Var_Request
674 {
675   /** The result of the operation. */
676   int ErrCode;
677
678   /** The socket number of the connection to the requestor. */
679   int Socket;
680
681   /** The error string in case of error. */
682   char ErrStr[LINE_SIZE];
683
684   /** The unique device ID. */
685   char DevUDN[NAME_SIZE];
686
687   /** The  service ID. */
688   char ServiceID[NAME_SIZE];
689
690   /** The name of the variable. */
691   char StateVarName[NAME_SIZE];
692
693   /** IP address of sender requesting the state variable. */
694   struct in_addr CtrlPtIPAddr;
695
696   /** The current value of the variable. This needs to be allocated by 
697    *  the caller.  When finished with it, the SDK frees this {\bf DOMString}. */
698   DOMString CurrentVal;
699 };
700
701 /** Represents the reply for the current value of a state variable in an
702     asynchronous call. */
703
704 struct Upnp_State_Var_Complete
705 {
706   /** The result of the operation. */
707   int ErrCode;
708
709   /** The control URL for the service. */
710   char CtrlUrl[NAME_SIZE];
711
712   /** The name of the variable. */
713   char StateVarName[NAME_SIZE];
714
715   /** The current value of the variable or error string in case of error. */
716   DOMString CurrentVal;
717 };
718
719 /** Returned along with a {\bf UPNP_EVENT_RECEIVED} callback.  */
720
721 struct Upnp_Event
722 {
723   /** The subscription ID for this subscription. */
724   Upnp_SID Sid;
725
726   /** The event sequence number. */
727   int EventKey;
728
729   /** The DOM tree representing the changes generating the event. */
730   IXML_Document *ChangedVariables;
731
732 };
733
734 /*
735  * This typedef is required by Doc++ to parse the last entry of the 
736  * Upnp_Discovery structure correctly.
737  */
738
739
740 /** Returned in a {\bf UPNP_DISCOVERY_RESULT} callback. */
741 struct Upnp_Discovery
742 {
743         /** The result code of the {\bf UpnpSearchAsync} call. */
744         int  ErrCode;                  
745                                      
746         /** The expiration time of the advertisement. */
747         int  Expires;                  
748                                      
749         /** The unique device identifier. */
750         char DeviceId[LINE_SIZE];      
751
752         /** The device type. */
753         char DeviceType[LINE_SIZE];    
754
755         /** The service type. */
756         char ServiceType[LINE_SIZE];
757
758         /** The service version. */
759         char ServiceVer[LINE_SIZE];    
760
761         /** The URL to the UPnP description document for the device. */
762         char Location[LINE_SIZE];      
763
764         /** The operating system the device is running. */
765         char Os[LINE_SIZE];            
766                                      
767         /** Date when the response was generated. */
768         char Date[LINE_SIZE];            
769                                      
770         /** Confirmation that the MAN header was understood by the device. */
771         char Ext[LINE_SIZE];           
772                                      
773         /** The host address of the device responding to the search. */
774         struct sockaddr_in DestAddr; 
775 };
776
777 /** Returned along with a {\bf UPNP_EVENT_SUBSCRIBE_COMPLETE} or {\bf
778  * UPNP_EVENT_UNSUBSCRIBE_COMPLETE} callback.  */
779
780 struct Upnp_Event_Subscribe {
781
782   /** The SID for this subscription.  For subscriptions, this only
783    *  contains a valid SID if the {\bf Upnp_EventSubscribe.result} field
784    *  contains a {\tt UPNP_E_SUCCESS} result code.  For unsubscriptions,
785    *  this contains the SID from which the subscription is being
786    *  unsubscribed.  */
787
788   Upnp_SID Sid;            
789
790   /** The result of the operation. */
791   int ErrCode;              
792
793   /** The event URL being subscribed to or removed from. */
794   char PublisherUrl[NAME_SIZE]; 
795
796   /** The actual subscription time (for subscriptions only). */
797   int TimeOut;              
798                               
799 };
800   
801 /** Returned along with a {\bf UPNP_EVENT_SUBSCRIPTION_REQUEST}
802  *  callback.  */
803
804 struct Upnp_Subscription_Request
805 {
806   /** The identifier for the service being subscribed to. */
807   char *ServiceId; 
808
809   /** Universal device name. */
810   char *UDN;       
811
812   /** The assigned subscription ID for this subscription. */
813   Upnp_SID Sid;
814
815 };
816
817
818 struct File_Info
819 {
820   /** The length of the file. A length less than 0 indicates the size 
821    *  is unknown, and data will be sent until 0 bytes are returned from
822    *  a read call. */
823   off_t file_length;
824
825   /** The time at which the contents of the file was modified;
826    *  The time system is always local (not GMT). */
827   time_t last_modified;
828
829   /** If the file is a directory, {\bf is_directory} contains
830    * a non-zero value. For a regular file, it should be 0. */
831   int is_directory;
832
833   /** If the file or directory is readable, this contains 
834    * a non-zero value. If unreadable, it should be set to 0. */
835   int is_readable;
836
837   /** The content type of the file. This string needs to be allocated 
838    *  by the caller using {\bf ixmlCloneDOMString}.  When finished 
839    *  with it, the SDK frees the {\bf DOMString}. */
840    
841   DOMString content_type;
842
843 };
844
845 /* The type of handle returned by the web server for open requests. */
846
847 typedef void *UpnpWebFileHandle;
848
849 /** The {\bf UpnpVirtualDirCallbacks} structure contains the pointers to
850  *  file-related callback functions a device application can register to
851  *  virtualize URLs.  
852  */
853 struct UpnpVirtualDirCallbacks
854 {
855   /** Called by the web server to query information on a file.  The callback
856    *  should return 0 on success or -1 on an error. */
857   int (*get_info) (
858     IN  const char *filename,     /** The name of the file to query. */
859     OUT struct File_Info *info    /** Pointer to a structure to store the 
860                                       information on the file. */
861     );
862                                   
863   /** Called by the web server to open a file.  The callback should return
864    *  a valid handle if the file can be opened.  Otherwise, it should return
865    *  {\tt NULL} to signify an error. */
866   UpnpWebFileHandle (*open)(
867     IN const char *filename,       /** The name of the file to open. */ 
868     IN enum UpnpOpenFileMode Mode  /** The mode in which to open the file. 
869                                        Valid values are {\tt UPNP_READ} or 
870                                        {\tt UPNP_WRITE}. */
871     );
872
873   /** Called by the web server to perform a sequential read from an open
874    *  file.  The callback should copy {\bf buflen} bytes from the file into
875    *  the buffer.
876    *  @return [int] An integer representing one of the following:
877    *    \begin{itemize}
878    *      \item {\tt 0}:  The file contains no more data (EOF).
879    *      \item {\tt >0}: A successful read of the number of bytes in the 
880    *                      return code.
881    *      \item {\tt <0}: An error occurred reading the file.
882    *    \end{itemzie}
883    */
884    int (*read) (
885      IN UpnpWebFileHandle fileHnd,  /** The handle of the file to read. */
886      OUT char *buf,                 /** The buffer in which to place the 
887                                         data. */
888      IN size_t buflen               /** The size of the buffer (i.e. the 
889                                         number of bytes to read). */
890      );
891
892   /** Called by the web server to perform a sequential write to an open
893    *  file.  The callback should write {\bf buflen} bytes into the file from
894    *  the buffer.  It should return the actual number of bytes written, 
895    *  which might be less than {\bf buflen} in the case of a write error.
896    */
897    int (*write) (
898      IN UpnpWebFileHandle fileHnd, /** The handle of the file to write. */
899      IN char *buf,                 /** The buffer with the bytes to write. */
900      IN size_t buflen              /** The number of bytes to write. */
901      );
902
903   /** Called by the web server to move the file pointer, or offset, into
904    *  an open file.  The {\bf origin} parameter determines where to start
905    *  moving the file pointer.  A value of {\tt SEEK_CUR} moves the
906    *  file pointer relative to where it is.  The {\bf offset} parameter can
907    *  be either positive (move forward) or negative (move backward).  
908    *  {\tt SEEK_END} moves relative to the end of the file.  A positive 
909    *  {\bf offset} extends the file.  A negative {\bf offset} moves backward 
910    *  in the file.  Finally, {\tt SEEK_SET} moves to an absolute position in 
911    *  the file. In this case, {\bf offset} must be positive.  The callback 
912    *  should return 0 on a successful seek or a non-zero value on an error.
913    */
914    int (*seek) (
915      IN UpnpWebFileHandle fileHnd,  /** The handle of the file to move the 
916                                         file pointer. */
917      IN off_t offset,                /** The number of bytes to move in the 
918                                         file.  Positive values move foward and 
919                                         negative values move backward.  Note 
920                                         that this must be positive if the 
921                                         {\bf origin} is {\tt SEEK_SET}. */
922      IN int origin                  /** The position to move relative to.  It 
923                                         can be {\tt SEEK_CUR} to move relative 
924                                         to the current position, 
925                                         {\tt SEEK_END} to move relative to 
926                                         the end of the file, or {\tt 
927                                         SEEK_SET} to specify an absolute 
928                                         offset. */
929      );
930
931    /** Called by the web server to close a file opened via the {\bf open}
932     *  callback.  It should return 0 on success, or a non-zero value on an 
933     *  error.
934     */
935    int (*close) (
936      IN UpnpWebFileHandle fileHnd   /** The handle of the file to close. */
937      );
938
939 };
940
941 typedef struct virtual_Dir_List
942 {
943     struct virtual_Dir_List *next;
944     char dirName[NAME_SIZE];
945 } virtualDirList;
946
947 /** All callback functions share the same prototype, documented below.
948  *  Note that any memory passed to the callback function
949  *  is valid only during the callback and should be copied if it
950  *  needs to persist.  This callback function needs to be thread
951  *  safe.  The context of the callback is always on a valid thread 
952  *  context and standard synchronization methods can be used.  Note, 
953  *  however, because of this the callback cannot call SDK functions
954  *  unless explicitly noted.
955  *
956  *  \verbatim
957       int CallbackFxn(Upnp_EventType EventType, void *Event, void *Cookie);
958     \endverbatim 
959  *
960  *  where \b EventType is the event that triggered the callback, 
961  *  \b Event is a structure that denotes event-specific information for that
962  *  event, and \b Cookie is the user data passed when the callback was
963  *  registered.
964  *
965  *  See \b Upnp_EventType for more information on the callback values and
966  *  the associated \b Event parameter.  
967  *
968  *  The return value of the callback is currently ignored. It may be used
969  *  in the future to communicate results back to the SDK.
970  */
971 typedef int (*Upnp_FunPtr)(
972         /*! [in] .*/
973         Upnp_EventType EventType,
974         /*! [in] .*/
975         void *Event,
976         /*! [in] .*/
977         void *Cookie);
978
979 /* @} Constants and Types */
980
981
982 #ifdef __cplusplus
983 extern "C" {
984 #endif /* __cplusplus */
985
986
987 /*!
988  * \name Initialization and Registration
989  *
990  * @{
991  */
992
993
994 /*!
995  * \brief Initializes the Linux SDK for UPnP Devices.
996  *
997  * \deprecated Kept for backwards compatibility. Use UpnpInit2 for new
998  * implementations.
999  *
1000  * This function must be called before any other API function can be called.
1001  * It should be called only once. Subsequent calls to this API return a
1002  * \c UPNP_E_INIT error code.
1003  *
1004  * Optionally, the application can specify a host IP address (in the
1005  * case of a multi-homed configuration) and a port number to use for
1006  * all UPnP operations.  Since a port number can be used only by one
1007  * process, multiple processes using the SDK must specify
1008  * different port numbers.
1009  *
1010  * If unspecified, the SDK will use the first adapter's IP address 
1011  * and an arbitrary port.
1012  *
1013  * This call is synchronous.
1014  *
1015  * \return An integer representing one of the following:
1016  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1017  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist 
1018  *             to initialize the SDK.
1019  *     \li \c UPNP_E_INIT: The SDK is already initialized. 
1020  *     \li \c UPNP_E_INIT_FAILED: The SDK initialization 
1021  *             failed for an unknown reason.
1022  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
1023  *     \li \c UPNP_E_LISTEN: An error occurred listening to a socket.
1024  *     \li \c UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
1025  *     \li \c UPNP_E_INTERNAL_ERROR: An internal error ocurred.
1026  */
1027 EXPORT_SPEC int UpnpInit(
1028         /*! The host local IP address to use, in string format, for example
1029          * "192.168.0.1", or \c NULL to use the first adapter's IP address. */
1030         const char *HostIP,
1031         /*! Local Port to listen for incoming connections
1032          * \c NULL will pick an arbitrary free port. */
1033         unsigned short DestPort);
1034
1035
1036
1037 /*!
1038  * \brief Terminates the Linux SDK for UPnP Devices.
1039  *
1040  * \li Checks for pending jobs and threads
1041  * \li Unregisters either the client or device 
1042  * \li Shuts down the Timer Thread
1043  * \li Stops the Mini Server
1044  * \li Uninitializes the Thread Pool
1045  * \li For Win32 cleans up Winsock Interface 
1046  * \li Cleans up mutex objects
1047  *
1048  * This function must be the last API function called. It should be called only
1049  * once. Subsequent calls to this API return a \c UPNP_E_FINISH error code.
1050  *
1051  *  \return An integer representing one of the following:
1052  *      \li \c UPNP_E_SUCCESS: The operation completed successfully.
1053  *      \li \c UPNP_E_FINISH: The SDK is already terminated or 
1054  *                                 it is not initialized. 
1055  */
1056 EXPORT_SPEC int UpnpFinish();
1057
1058
1059 /*!
1060  * \brief Returns the internal server IPv4 UPnP listening port.
1061  *
1062  * If '0' is used as the port number in \b UpnpInit, then this function can be
1063  * used to retrieve the actual port allocated to the SDK.
1064  *
1065  * \return
1066  *      \li On success: The port on which an internal server is listening for IPv4 UPnP
1067  *              related requests.
1068  *      \li On error: 0 is returned if \b UpnpInit has not succeeded.
1069  */
1070 EXPORT_SPEC unsigned short UpnpGetServerPort();
1071
1072
1073 /*!
1074  * \brief Returns the local IPv4 listening ip address.
1075  *
1076  * If \c NULL is used as the IPv4 address in \b UpnpInit, then this function can
1077  * be used to retrieve the actual interface address on which device is running.
1078  *
1079  * \return
1080  *      \li On success: The IPv4 address on which an internal server is
1081  *              listening for UPnP related requests.
1082  *      \li On error: \c NULL is returned if \b UpnpInit has not succeeded.
1083  */
1084 EXPORT_SPEC char *UpnpGetServerIpAddress();
1085
1086
1087 /*!
1088  * \brief Registers a device application with the UPnP Library.
1089  *
1090  * A device application cannot make any other API calls until it registers
1091  * using this function.
1092  *
1093  * Device applications can also register as control points (see 
1094  * \b UpnpRegisterClient to get a control point handle to perform control
1095  * point functionality).
1096  *
1097  * This is a synchronous call and does not generate any callbacks. Callbacks
1098  * can occur as soon as this function returns.
1099  *
1100  *  \return An integer representing one of the following:
1101  *      \li \c UPNP_E_SUCCESS: The operation completed successfully.
1102  *      \li \c UPNP_E_FINISH: The SDK is already terminated or is not
1103  *              initialized.
1104  *      \li \c UPNP_E_INVALID_DESC: The description document was not 
1105  *              a valid device description.
1106  *      \li \c UPNP_E_INVALID_URL: The URL for the description document 
1107  *              is not valid.
1108  *      \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd 
1109  *              is not a valid pointer or \b DescURL is \c NULL.
1110  *      \li \c UPNP_E_NETWORK_ERROR: A network error occurred.
1111  *      \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
1112  *              to a socket.
1113  *      \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
1114  *              from a socket.
1115  *      \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
1116  *      \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the 
1117  *              socket.
1118  *      \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently 
1119  *              allocated.
1120  *      \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to 
1121  *              register this root device.
1122  */
1123 EXPORT_SPEC int UpnpRegisterRootDevice(
1124         /*! [in] Pointer to a string containing the description URL for this root device
1125          * instance. */
1126         const char *DescUrl,
1127         /*! [in] Pointer to the callback function for receiving asynchronous events. */
1128         Upnp_FunPtr Callback,
1129         /*! [in] Pointer to user data returned with the callback function when invoked. */
1130         const void *Cookie,
1131         /*! [out] Pointer to a variable to store the new device handle. */
1132         UpnpDevice_Handle *Hnd);
1133
1134 /*!
1135  * \brief Registers a device application with the UPnP Library. Similar to
1136  * \b UpnpRegisterRootDevice, except that it also allows the description
1137  * document to be specified as a file or a memory buffer.
1138  *
1139  * The description can also be configured to have the correct IP and port
1140  * address.
1141  *
1142  * NOTE: For the configuration to be functional, the internal web server
1143  * MUST be present. In addition, the web server MUST be activated
1144  * (using \b UpnpSetWebServerRootDir) before calling this function.
1145  * The only condition where the web server can be absent is if the 
1146  * description document is specified as a URL and no configuration is 
1147  * required (i.e. <tt>config_baseURL = 0</tt>.)
1148  *
1149  * This is a synchronous call and does not generate any callbacks. Callbacks
1150  * can occur as soon as this function returns.
1151  *
1152  * Examples of using different types of description documents:
1153  * \verbatim
1154    1) Description specified as a URL:
1155          descriptionType == UPNPREG_URL_DESC
1156          description is the URL
1157          bufferLen = 0 (ignored)
1158    2) Description specified as a file:
1159          descriptionType == UPNPREG_FILENAME_DESC
1160          description is a filename
1161          bufferLen = 0 (ignored)
1162    3) Description specified as a memory buffer:
1163          descriptionType == UPNPREG_BUF_DESC
1164          description is pointer to a memory buffer
1165          bufferLen == length of memory buffer
1166    \endverbatim
1167  *
1168  * \return An integer representing one of the following:
1169  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1170  *     \li \c UPNP_E_FINISH: The SDK is already terminated or 
1171  *                                is not initialized.
1172  *     \li \c UPNP_E_INVALID_DESC: The description document is not 
1173  *             a valid device description.
1174  *     \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd 
1175  *             is not a valid pointer or \b DescURL is \c NULL.
1176  *     \li \c UPNP_E_NETWORK_ERROR: A network error occurred.
1177  *     \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
1178  *             to a socket.
1179  *     \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
1180  *             from a socket.
1181  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
1182  *     \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting the 
1183  *             socket.
1184  *     \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently 
1185  *             allocated.
1186  *     \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to 
1187  *             register this root device.
1188  *     \li \c UPNP_E_URL_TOO_BIG: Length of the URL is bigger than the 
1189  *             internal buffer.
1190  *     \li \c UPNP_E_FILE_NOT_FOUND: The description file could not 
1191  *             be found.
1192  *     \li \c UPNP_E_FILE_READ_ERROR: An error occurred reading the 
1193  *             description file.
1194  *     \li \c UPNP_E_INVALID_URL: The URL to the description document 
1195  *             is invalid.
1196  *     \li \c UPNP_E_EXT_NOT_XML: The URL to the description document 
1197  *             or file should have a <tt>.xml</tt> extension.
1198  *     \li \c UPNP_E_NO_WEB_SERVER: The internal web server has been 
1199  *             compiled out; the SDK cannot configure itself from the 
1200  *             description document.
1201  */
1202 EXPORT_SPEC int UpnpRegisterRootDevice2(
1203         /*! [in] The type of the description document. */
1204         Upnp_DescType descriptionType,
1205         /*! [in] Treated as a URL, file name or memory buffer depending on
1206          * description type. */
1207         const char* description,
1208         /*! [in] The length of memory buffer if passing a description in a buffer,
1209          * otherwise it is ignored. */
1210         size_t bufferLen,
1211         /*! [in] If nonzero, \c URLBase of description document is configured and
1212          * the description is served using the internal web server. */
1213         int config_baseURL,
1214         /*! [in] Pointer to the callback function for receiving asynchronous events. */
1215         Upnp_FunPtr Fun,
1216         /*! [in] Pointer to user data returned with the callback function when
1217          * invoked. */
1218         const void* Cookie,
1219         /*! [out] Pointer to a variable to store the new device handle. */
1220         UpnpDevice_Handle* Hnd);
1221
1222
1223 /*!
1224  * \brief Unregisters a root device registered with \b UpnpRegisterRootDevice or
1225  * \b UpnpRegisterRootDevice2.
1226  *
1227  * After this call, the \b UpnpDevice_Handle is no longer valid. For all
1228  * advertisements that have not yet expired, the SDK sends a device unavailable
1229  * message automatically.
1230  *
1231  * This is a synchronous call and generates no callbacks. Once this call
1232  * returns, the SDK will no longer generate callbacks to the application.
1233  *
1234  * \return An integer representing one of the following:
1235  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1236  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device handle.
1237  */
1238 EXPORT_SPEC int UpnpUnRegisterRootDevice(
1239         /*! [in] The handle of the root device instance to unregister. */
1240         UpnpDevice_Handle Hnd);
1241
1242
1243 /*!
1244  * \brief Registers a control point application with the UPnP Library.
1245  *
1246  * A control point application cannot make any other API calls until it
1247  * registers using this function.
1248  *
1249  * \b UpnpRegisterClient is a synchronous call and generates no callbacks.
1250  * Callbacks can occur as soon as this function returns.
1251  *
1252  * \return An integer representing one of the following:
1253  *      \li \c UPNP_E_SUCCESS: The operation completed successfully.
1254  *      \li \c UPNP_E_FINISH: The SDK is already terminated or 
1255  *                            is not initialized. 
1256  *      \li \c UPNP_E_INVALID_PARAM: Either \b Callback or \b Hnd 
1257  *              is not a valid pointer.
1258  *      \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1259  *              register this control point.
1260  */
1261 EXPORT_SPEC int UpnpRegisterClient(
1262         /*! [in] Pointer to a function for receiving asynchronous events. */
1263         Upnp_FunPtr Callback,
1264         /*! [in] Pointer to user data returned with the callback function when invoked. */
1265         const void *Cookie,
1266         /*! [out] Pointer to a variable to store the new control point handle. */
1267         UpnpClient_Handle *Hnd);
1268
1269
1270 /*!
1271  * \brief Unregisters a control point application, unsubscribing all active
1272  * subscriptions.
1273  *
1274  * This function unregisters a client registered with UpnpRegisterclient or
1275  * UpnpRegisterclient2. After this call, the \b UpnpClient_Handle is no longer
1276  * valid. The UPnP Library generates no more callbacks after this function
1277  * returns.
1278  *
1279  * \b UpnpUnRegisterClient is a synchronous call and generates no
1280  * callbacks.
1281  *
1282  * \return An integer representing one of the following:
1283  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1284  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control point handle.
1285  */
1286 EXPORT_SPEC int UpnpUnRegisterClient(
1287         /*! [in] The handle of the control point instance to unregister. */
1288         UpnpClient_Handle Hnd);
1289
1290
1291 /*!
1292  * \deprecated Use \b UpnpSetMaxContentLength instead.
1293  *
1294  * Warning: the Handle argument provided here is not used, so the effect
1295  * of this function is global to the SDK (= same as \b UpnpSetMaxContentLength).
1296  */
1297 EXPORT_SPEC int UpnpSetContentLength(
1298         /*! [in] The handle of the device instance for which the coincoming content
1299          * length needs to be set. */
1300         UpnpClient_Handle Hnd,
1301         /*! [in] Permissible content length */
1302         int contentLength);
1303
1304
1305 /*!
1306  * \brief Sets the maximum content-length that the SDK will process on an
1307  * incoming SOAP requests or responses.
1308  *
1309  * This API allows devices that have memory constraints to exhibit consistent
1310  * behaviour if the size of the incoming SOAP message exceeds the memory that
1311  * device can allocate.
1312  *
1313  * The default maximum content-length is \c DEFAULT_SOAP_CONTENT_LENGTH 
1314  * = 16K bytes.
1315  *  
1316  * \return An integer representing one of the following:
1317  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1318  */
1319 EXPORT_SPEC int UpnpSetMaxContentLength(
1320         /*! [in] The maximum permissible content length for incoming SOAP actions,
1321          * in bytes. */
1322         size_t contentLength);
1323
1324
1325 /* @} Initialization and Registration */
1326
1327
1328 /******************************************************************************
1329  ******************************************************************************
1330  *                                                                            *
1331  *                        D I S C O V E R Y                                   *
1332  *                                                                            *
1333  ******************************************************************************
1334  ******************************************************************************/
1335
1336
1337 /*!
1338  * \name Discovery
1339  *
1340  * @{
1341  */
1342
1343
1344 /*!
1345  * \brief Searches for devices matching the given search target.
1346  *
1347  * The function returns immediately and the SDK calls the default callback
1348  * function, registered during the \b UpnpRegisterClient call, for each
1349  * matching root device, device, or service. The application specifies the
1350  * search type by the \b Target parameter.  
1351  *
1352  * This function searches for the devices for the provided maximum time.
1353  * It is an asynchronous function. It schedules a search job and returns. 
1354  * The client is notified about the search results after search timer.
1355  *
1356  * Note that there is no way for the SDK to distinguish which client
1357  * instance issued a particular search.  Therefore, the client can get
1358  * search callbacks that do not match the original criteria of the search.
1359  * Also, the application will receive multiple callbacks for each search.
1360  *
1361  * \return An integer representing one of the following:
1362  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1363  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1364  *             point handle.
1365  *     \li \c UPNP_E_INVALID_PARAM: \b Target is \c NULL.
1366  */
1367 EXPORT_SPEC int UpnpSearchAsync(
1368         /*! The handle of the client performing the search. */
1369         UpnpClient_Handle Hnd,
1370         /*! The time, in seconds, to wait for responses. If the time is greater
1371          * than \c MAX_SEARCH_TIME then the time is set to \c MAX_SEARCH_TIME.
1372          * If the time is less than \c MIN_SEARCH_TIME then the time is set to
1373          * \c MIN_SEARCH_TIME. */ 
1374         int Mx,
1375         /*! The search target as defined in the UPnP Device Architecture v1.0
1376          * specification. */
1377         const char *TTarget_constarget_const,
1378         /*! The user data to pass when the callback function is invoked. */
1379         const void *Cookie_const); 
1380
1381 /*!
1382  * \brief Sends out the discovery announcements for all devices and services
1383  * for a device.
1384  *
1385  * Each announcement is made with the same expiration time.
1386  *
1387  * This is a synchronous call.
1388  *
1389  * \return An integer representing one of the following:
1390  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1391  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid 
1392  *             device handle.
1393  *     \li \c UPNP_E_OUTOF_MEMORY: There are insufficient resources to 
1394  *             send future advertisements.
1395  */
1396 EXPORT_SPEC int UpnpSendAdvertisement(
1397         /*! The device handle for which to send out the announcements. */
1398         UpnpDevice_Handle Hnd,
1399         /*! The expiration age, in seconds, of the announcements. */
1400         int Exp);
1401
1402
1403 /* @} Discovery */
1404
1405
1406 /******************************************************************************
1407  ******************************************************************************
1408  *                                                                            *
1409  *                            C O N T R O L                                   *
1410  *                                                                            *
1411  ******************************************************************************
1412  ******************************************************************************/
1413
1414
1415 /*!
1416  * \name Control
1417  *
1418  * @{
1419  */
1420
1421
1422 /*!
1423  * \brief Queries the state of a state variable of a service on another device.
1424  *
1425  * \deprecated
1426  * <b>The use of this function is deprecated by the UPnP Forum</b>.
1427  *
1428  * This is a synchronous call.
1429  *
1430  * A positive return value indicates a SOAP error code, whereas a negative
1431  * return code indicates an SDK error code.
1432  *
1433  * \return An integer representing one of the following:
1434  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1435  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1436  *             point handle.
1437  *     \li \c UPNP_E_INVALID_URL: \b ActionUrl is not a valid URL.
1438  *     \li \c UPNP_E_INVALID_DESC: The XML document was not 
1439  *             found or it does not contain a valid XML description.
1440  *     \li \c UPNP_E_INVALID_PARAM: \b StVarVal is not a valid 
1441  *             pointer or \b VarName or \b ActionUrl is \c NULL. 
1442  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1443  *             complete this operation.
1444  *     \li \c UPNP_SOAP_E_INVALID_VAR: The given variable is invalid 
1445  *             according to the device.
1446  */
1447 EXPORT_SPEC int UpnpGetServiceVarStatus(
1448         /*! [in] The handle of the control point. */
1449         UpnpClient_Handle Hnd,
1450         /*! [in] The URL of the service. */
1451         const char *ActionURL,
1452         /*! [in] The name of the variable to query. */
1453         const char *VarName,
1454         /*! [out] The pointer to store the value for \b VarName. The SDK allocates
1455          * this string and the caller needs to free it using
1456          * \b ixmlFreeDOMString. */
1457         DOMString *StVarVal);
1458
1459
1460 /*!
1461  * \brief Queries the state of a variable of a service, generating a callback
1462  * when the operation is complete.
1463  *
1464  * \deprecated
1465  * <b>The use of this function is deprecated by the UPnP Forum</b>.
1466  *
1467  * \return An integer representing one of the following:
1468  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1469  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1470  *             point handle.
1471  *     \li \c UPNP_E_INVALID_URL: The \b ActionUrl is not a valid URL.
1472  *     \li \c UPNP_E_INVALID_PARAM: \b VarName, \b Fun or 
1473  *             \b ActionUrl is not a valid pointer.
1474  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1475  *             complete this operation.
1476  */
1477 EXPORT_SPEC int UpnpGetServiceVarStatusAsync(
1478         /*! [in] The handle of the control point. */
1479         UpnpClient_Handle Hnd,
1480         /*! [in] The URL of the service. */
1481         const char *ActionURL,
1482         /*! [in] The name of the variable to query. */
1483         const char *VarName,
1484         /*! [in] Pointer to a callback function to be invoked when the operation
1485          * is complete. */
1486         Upnp_FunPtr Fun,
1487         /*! [in] Pointer to user data to pass to the callback function when invoked. */
1488         const void *Cookie);
1489
1490
1491 /*!
1492  * \brief Sends a message to change a state variable in a service.
1493  *
1494  * This is a synchronous call that does not return until the action is complete.
1495  * 
1496  * Note that a positive return value indicates a SOAP-protocol error code.
1497  * In this case,  the error description can be retrieved from \b RespNode.
1498  * A negative return value indicates an SDK error.
1499  *
1500  * \return An integer representing one of the following:
1501  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1502  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1503  *             point handle.
1504  *     \li \c UPNP_E_INVALID_URL: \b ActionUrl is not a valid URL.
1505  *     \li \c UPNP_E_INVALID_ACTION: This action is not valid.
1506  *     \li \c UPNP_E_INVALID_DEVICE: \b DevUDN is not a 
1507  *             valid device.
1508  *     \li \c UPNP_E_INVALID_PARAM: \b ServiceType, \b Action, 
1509  *             \b ActionUrl, or 
1510  *             \b RespNode is not a valid pointer.
1511  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1512  *             complete this operation.
1513  */
1514 EXPORT_SPEC int UpnpSendAction(
1515         /*! [in] The handle of the control point sending the action. */
1516         UpnpClient_Handle Hnd,
1517         /*! [in] The action URL of the service. */
1518         const char *ActionURL,
1519         /*! [in] The type of the service. */
1520         const char *ServiceType,
1521         /*! [in] This parameter is ignored and must be \c NULL. */
1522         const char *DevUDN,
1523         /*! [in] The DOM document for the action. */
1524         IXML_Document *Action,
1525         /*! [out] The DOM document for the response to the action. The SDK allocates
1526          * this document and the caller needs to free it. */
1527         IXML_Document **RespNode);
1528
1529
1530 /*!
1531  * \brief Sends a message to change a state variable in a service.
1532  *
1533  * This is a synchronous call that does not return until the action is complete.
1534  *
1535  * Note that a positive return value indicates a SOAP-protocol error code.
1536  * In this case,  the error description can be retrieved from \b RespNode.
1537  * A negative return value indicates an SDK error.
1538  *
1539  * \return An integer representing one of the following:
1540  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1541  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1542  *             point handle.
1543  *     \li \c UPNP_E_INVALID_URL: \b ActionUrl is not a valid URL.
1544  *     \li \c UPNP_E_INVALID_ACTION: This action is not valid.
1545  *     \li \c UPNP_E_INVALID_DEVICE: \b DevUDN is not a 
1546  *             valid device.
1547  *     \li \c UPNP_E_INVALID_PARAM: \b ServiceType, \b Action, 
1548  *             \b ActionUrl, or 
1549  *             \b RespNode is not a valid pointer.
1550  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1551  *             complete this operation.
1552  */
1553 EXPORT_SPEC int UpnpSendActionEx(
1554         /*! [in] The handle of the control point sending the action. */
1555         UpnpClient_Handle Hnd,
1556         /*! [in] The action URL of the service. */
1557         const char *ActionURL,
1558         /*! [in] The type of the service. */
1559         const char *ServiceType,
1560         /*! [in] This parameter is ignored and must be \c NULL. */
1561         const char *DevUDN,
1562         /*! [in] The DOM document for the SOAP header. This may be \c NULL if the
1563          * header is not required. */
1564         IXML_Document *Header,
1565         /*! [in] The DOM document for the action. */
1566         IXML_Document *Action,
1567         /*! [out] The DOM document for the response to the action. The SDK allocates
1568          * this document and the caller needs to free it. */
1569         IXML_Document **RespNode);
1570
1571
1572 /*!
1573  * \brief Sends a message to change a state variable in a service, generating a
1574  * callback when the operation is complete.
1575  * 
1576  * See \b UpnpSendAction for comments on positive return values. These 
1577  * positive return values are sent in the event struct associated with the
1578  * \c UPNP_CONTROL_ACTION_COMPLETE event.
1579  *
1580  * \return An integer representing one of the following:
1581  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1582  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1583  *             point handle.
1584  *     \li \c UPNP_E_INVALID_URL: \b ActionUrl is an invalid URL.
1585  *     \li \c UPNP_E_INVALID_DEVICE: \b DevUDN is an invalid device.
1586  *     \li \c UPNP_E_INVALID_PARAM: Either \b Fun is not a valid 
1587  *             callback function or \b ServiceType, \b Act, or 
1588  *             \b ActionUrl is \c NULL.
1589  *     \li \c UPNP_E_INVALID_ACTION: This action is not valid.
1590  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1591  *             complete this operation.
1592  */
1593 EXPORT_SPEC int UpnpSendActionAsync(
1594         /*! [in] The handle of the control point sending the action. */
1595         UpnpClient_Handle Hnd,
1596         /*! [in] The action URL of the service. */
1597         const char *ActionURL,
1598         /*! [in] The type of the service. */
1599         const char *ServiceType,
1600         /*! [in] This parameter is ignored and must be \c NULL. */
1601         const char *DevUDN,
1602         /*! [in] The DOM document for the action to perform on this device. */
1603         IXML_Document *Action,
1604         /*! [in] Pointer to a callback function to be invoked when the operation
1605          * completes. */
1606         Upnp_FunPtr Fun,
1607         /*! [in] Pointer to user data that to be passed to the callback when
1608          * invoked. */
1609         const void *Cookie);
1610
1611
1612 /*!
1613  * \brief Sends a message to change a state variable in a service, generating a
1614  * callback when the operation is complete.
1615  *
1616  * See \b UpnpSendAction for comments on positive return values. These 
1617  * positive return values are sent in the event struct associated with the
1618  * \c UPNP_CONTROL_ACTION_COMPLETE event.
1619  *
1620  * \return An integer representing one of the following:
1621  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1622  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1623  *             point handle.
1624  *     \li \c UPNP_E_INVALID_URL: \b ActionUrl is an invalid URL.
1625  *     \li \c UPNP_E_INVALID_DEVICE: \b DevUDN is an invalid device.
1626  *     \li \c UPNP_E_INVALID_PARAM: Either \b Fun is not a valid 
1627  *             callback function or \b ServiceType, \b Act, or 
1628  *             \b ActionUrl is \c NULL.
1629  *     \li \c UPNP_E_INVALID_ACTION: This action is not valid.
1630  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1631  *             complete this operation.
1632  */
1633 EXPORT_SPEC int UpnpSendActionExAsync(
1634         /*! [in] The handle of the control point sending the action. */
1635         UpnpClient_Handle Hnd,
1636         /*! [in] The action URL of the service. */
1637         const char *ActionURL,
1638         /*! [in] The type of the service. */
1639         const char *ServiceType,
1640         /*! [in] This parameter is ignored and must be \c NULL. */
1641         const char *DevUDN,
1642         /*! [in] The DOM document for the SOAP header. This may be \c NULL if the
1643          * header is not required. */
1644         IXML_Document *Header,
1645         /*! [in] The DOM document for the action to perform on this device. */
1646         IXML_Document *Action,
1647         /*! [in] Pointer to a callback function to be invoked when the operation
1648          * completes. */
1649         Upnp_FunPtr Fun,
1650         /*! [in] Pointer to user data that to be passed to the callback when
1651          * invoked. */
1652         const void *Cookie);
1653
1654
1655 /*! @} Control */
1656
1657
1658 /******************************************************************************
1659  ******************************************************************************
1660  *                                                                            *
1661  *                        E V E N T I N G                                     *
1662  *                                                                            *
1663  ******************************************************************************
1664  ******************************************************************************/
1665
1666
1667 /*!
1668  * \name Eventing
1669  *
1670  * @{
1671  */
1672
1673
1674 /*!
1675  * \brief Accepts a subscription request and sends out the current state of the
1676  * eventable variables for a service.
1677  *
1678  * The device application should call this function when it receives a
1679  * \c UPNP_EVENT_SUBSCRIPTION_REQUEST callback.
1680  *
1681  * This function is synchronous and generates no callbacks.
1682  *
1683  * This function can be called during the execution of a callback function.
1684  *
1685  * \return An integer representing one of the following:
1686  *      \li \c UPNP_E_SUCCESS: The operation completed successfully.
1687  *      \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device 
1688  *              handle.
1689  *      \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId 
1690  *              pair refers to an invalid service. 
1691  *      \li \c UPNP_E_INVALID_SID: The specified subscription ID is not 
1692  *              valid.
1693  *      \li \c UPNP_E_INVALID_PARAM: Either \b VarName, 
1694  *              \b NewVal, \b DevID, or \b ServID is not a valid 
1695  *              pointer or \b cVariables is less than zero.
1696  *      \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1697  *              complete this operation.
1698  */
1699 EXPORT_SPEC int UpnpAcceptSubscription(
1700         /*! [in] The handle of the device. */
1701         UpnpDevice_Handle Hnd,
1702         /*! [in] The device ID of the subdevice of the service generating the event. */
1703         const char *DevID,
1704         /*! [in] The unique service identifier of the service generating the event. */
1705         const char *ServID,
1706         /*! [in] Pointer to an array of event variables. */
1707         const char **VarName,
1708         /*! [in] Pointer to an array of values for the event variables. */
1709         const char **NewVal,
1710         /*! [in] The number of event variables in \b VarName. */
1711         int cVariables,
1712         /*! [in] The subscription ID of the newly registered control point. */
1713         const Upnp_SID SubsId);
1714
1715
1716 /*!
1717  * \brief Similar to \b UpnpAcceptSubscription() except that it takes a DOM
1718  * document for the variables to event rather than an array of strings.
1719  *
1720  * This function is sychronous and generates no callbacks.
1721  *
1722  * This function can be called during the execution of a callback function.
1723  *
1724  * \return An integer representing one of the following:
1725  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1726  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device 
1727  *             handle.
1728  *     \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId 
1729  *             pair refers to an invalid service. 
1730  *     \li \c UPNP_E_INVALID_SID: The specified subscription ID is not 
1731  *             valid.
1732  *     \li \c UPNP_E_INVALID_PARAM: Either \b VarName,  
1733  *             \b NewVal, \b DevID, \b ServID, or \b PropSet 
1734  *             is not a valid pointer.
1735  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1736  *             complete this operation.
1737  */
1738 EXPORT_SPEC int UpnpAcceptSubscriptionExt(
1739         /*! [in] The handle of the device. */
1740         UpnpDevice_Handle Hnd,
1741         /*! [in] The device ID of the subdevice of the service generating the event. */
1742         const char *DevID,
1743         /*! [in] The unique service identifier of the service generating the event. */
1744         const char *ServID,
1745         /*! [in] The DOM document for the property set. Property set documents must
1746          * conform to the XML schema defined in section 4.3 of the Universal
1747          * Plug and Play Device Architecture specification. */
1748         IXML_Document *PropSet,
1749         /*! [in] The subscription ID of the newly registered control point. */
1750         Upnp_SID SubsId);
1751
1752
1753 /*!
1754  * \brief Sends out an event change notification to all control points
1755  * subscribed to a particular service.
1756  *
1757  * This function is synchronous and generates no callbacks.
1758  *
1759  * This function may be called during a callback function to send out a
1760  * notification.
1761  *
1762  * \return An integer representing one of the following:
1763  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1764  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device 
1765  *             handle.
1766  *     \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId 
1767  *             pair refers to an invalid service.
1768  *     \li \c UPNP_E_INVALID_PARAM: Either \b VarName, \b NewVal, 
1769  *              \b DevID, or \b ServID is not a valid pointer or 
1770  *              \b cVariables is less than zero.
1771  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1772  *             complete this operation.
1773  */
1774 EXPORT_SPEC int UpnpNotify(
1775         /*! [in] The handle to the device sending the event. */
1776         UpnpDevice_Handle,
1777         /*! [in] The device ID of the subdevice of the service generating the event. */
1778         const char *DevID,
1779         /*! [in] The unique identifier of the service generating the event. */
1780         const char *ServID,
1781         /*! [in] Pointer to an array of variables that have changed. */
1782         const char **VarName,
1783         /*! [in] Pointer to an array of new values for those variables. */
1784         const char **NewVal,
1785         /*! [in] The count of variables included in this notification. */
1786         int cVariables);
1787
1788
1789 /*!
1790  * \brief Similar to \b UpnpNotify except that it takes a DOM document for the
1791  * event rather than an array of strings.
1792  *
1793  * This function is synchronous and generates no callbacks.
1794  *
1795  * This function may be called during a callback function to send out a
1796  * notification.
1797  *
1798  * \return An integer representing one of the following:
1799  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1800  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device 
1801  *             handle.
1802  *     \li \c UPNP_E_INVALID_SERVICE: The \b DevId/\b ServId 
1803  *             pair refers to an invalid service.
1804  *     \li \c UPNP_E_INVALID_PARAM: Either \b VarName, \b NewVal, 
1805  *              \b DevID, \b ServID, or \b PropSet 
1806  *              is not a valid pointer or \b cVariables is less than zero.
1807  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1808  *             complete this operation.
1809  */
1810 EXPORT_SPEC int UpnpNotifyExt(
1811         /*! [in] The handle to the device sending the event. */
1812         UpnpDevice_Handle,
1813         /*! [in] The device ID of the subdevice of the service generating the event. */
1814         const char *DevID,
1815         /*! [in] The unique identifier of the service generating the event. */
1816         const char *ServID,
1817         /*! [in] The DOM document for the property set. Property set documents must
1818          * conform to the XML schema defined in section 4.3 of the Universal
1819          * Plug and Play Device Architecture specification. */
1820         IXML_Document *PropSet);
1821
1822
1823 /*!
1824  * \brief Renews a subscription that is about to expire.
1825  *
1826  * This function is synchronous.
1827  *
1828  * \return An integer representing one of the following:
1829  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1830  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1831  *             point handle.
1832  *     \li \c UPNP_E_INVALID_PARAM: \b Timeout is not a valid pointer.
1833  *     \li \c UPNP_E_INVALID_SID: The SID being passed to this function 
1834  *             is not a valid subscription ID.
1835  *     \li \c UPNP_E_NETWORK_ERROR: A network error occured. 
1836  *     \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
1837  *             to a socket.
1838  *     \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
1839  *             from a socket.
1840  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.  
1841  *     \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to 
1842  *             \b PublisherUrl.
1843  *     \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating a socket.
1844  *     \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from 
1845  *             the publisher.
1846  *     \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused 
1847  *             the subscription renew.
1848  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1849  *             complete this operation.
1850  */
1851 EXPORT_SPEC int UpnpRenewSubscription(
1852         /*! [in] The handle of the control point that is renewing the subscription. */
1853         UpnpClient_Handle Hnd,
1854         /*! [in,out] Pointer to a variable containing the requested subscription time.
1855          * Upon return, it contains the actual renewal time. */
1856         int *TimeOut,
1857         /*! [in] The ID for the subscription to renew. */
1858         const Upnp_SID SubsId);
1859
1860
1861 /*!
1862  * \brief Renews a subscription that is about to expire, generating a callback
1863  * when the operation is complete.
1864  *
1865  * Note that many of the error codes for this function are returned in
1866  * the \b UpnpEventSubscribe structure.  In those cases, the function
1867  * returns \c UPNP_E_SUCCESS and the appropriate error code will
1868  * be in the <b>UpnpEventSubscribe.ErrCode</b> field in the \b Event
1869  * structure passed to the callback.
1870  *
1871  * \return An integer representing one of the following:
1872  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1873  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1874  *             point handle.
1875  *     \li \c UPNP_E_INVALID_SID: The \b SubsId is not a valid 
1876  *             subscription ID.
1877  *     \li \c UPNP_E_INVALID_PARAM: Either \b Fun is not a valid 
1878  *             callback function pointer or \b Timeout is less than zero 
1879  *             but is not \c UPNP_INFINITE.
1880  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1881  *             complete this operation.
1882  *     \li \c UPNP_E_NETWORK_ERROR: A network error occured (returned in 
1883  *             the <b>UpnpEventSubscribe.ErrCode</b> field as part of the 
1884  *             callback).
1885  *     \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
1886  *             to a socket (returned in the <b>UpnpEventSubscribe.ErrCode</b> 
1887  *             field as part of the callback).
1888  *     \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading  
1889  *             from a socket (returned in the 
1890  *             <b>UpnpEventSubscribe.ErrCode</b> field as part of the 
1891  *             callback).
1892  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding the socket 
1893  *             (returned in the <b>UpnpEventSubscribe.ErrCode</b> field as 
1894  *             part of the callback).
1895  *     \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to 
1896  *             \b PublisherUrl (returned in the \b 
1897  *             UpnpEventSubscribe.ErrCode field as part of the callback).
1898  *     \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating socket (
1899  *             returned in the <b>UpnpEventSubscribe.ErrCode</b> field as 
1900  *             part of the callback).
1901  *     \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from 
1902  *             the publisher (returned in the \b 
1903  *             UpnpEventSubscribe.ErrCode field as part of the callback).
1904  *     \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused 
1905  *             the subscription request (returned in the \b 
1906  *             UpnpEventSubscribe.ErrCode field as part of the callback).
1907  */
1908 EXPORT_SPEC int UpnpRenewSubscriptionAsync(
1909         /*! [in] The handle of the control point that is renewing the subscription. */
1910         UpnpClient_Handle Hnd,
1911         /*! [in] The requested subscription time. The actual timeout value is
1912          * returned when the callback function is called. */
1913         int TimeOut,
1914         /*! [in] The ID for the subscription to renew. */
1915         Upnp_SID SubsId,
1916         /*! [in] Pointer to a callback function to be invoked when the renewal is
1917          * complete. */
1918         Upnp_FunPtr Fun,
1919         /*! [in] Pointer to user data passed to the callback function when invoked. */
1920         const void *Cookie);
1921
1922
1923 /*!
1924  * \brief Sets the maximum number of subscriptions accepted per service.
1925  *
1926  * The default value accepts as many as system resources allow. If the number
1927  * of current subscriptions for a service is greater than the requested value,
1928  * the SDK accepts no new subscriptions or renewals, however, the SDK does not
1929  * remove any current subscriptions.
1930  *
1931  * \return An integer representing one of the following:
1932  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1933  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device 
1934  *             handle.
1935  */
1936 EXPORT_SPEC int UpnpSetMaxSubscriptions(  
1937         /*! The handle of the device for which the maximum number of
1938          * subscriptions is being set. */
1939         UpnpDevice_Handle Hnd,
1940         /*! The maximum number of subscriptions to be allowed per service. */
1941         int MaxSubscriptions);
1942
1943
1944 /*!
1945  * \brief Sets the maximum time-out accepted for a subscription request or
1946  * renewal.
1947  *
1948  * The default value accepts the time-out set by the control point.
1949  * If a control point requests a subscription time-out less than or equal to
1950  * the maximum, the SDK grants the value requested by the control point. If the
1951  * time-out is greater, the SDK returns the maximum value.
1952  *
1953  * \return An integer representing one of the following:
1954  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1955  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid device 
1956  *             handle.
1957  */
1958 EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut(  
1959         /*! The handle of the device for which the maximum subscription
1960          * time-out is being set. */
1961         UpnpDevice_Handle Hnd,
1962         /*! The maximum subscription time-out to be accepted. */
1963         int MaxSubscriptionTimeOut);
1964
1965
1966 /*!
1967  * \brief Registers a control point to receive event notifications from another
1968  * device.
1969  *
1970  * This operation is synchronous.
1971  *
1972  * \return An integer representing one of the following:
1973  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
1974  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
1975  *             point handle.
1976  *     \li \c UPNP_E_INVALID_URL: \b PublisherUrl is not a valid URL.
1977  *     \li \c UPNP_E_INVALID_PARAM: \b Timeout is not a valid pointer 
1978  *             or \b SubsId or \b PublisherUrl is \c NULL.
1979  *     \li \c UPNP_E_NETWORK_ERROR: A network error occured. 
1980  *     \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
1981  *             to a socket.
1982  *     \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
1983  *             from a socket.
1984  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
1985  *     \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to 
1986  *             \b PublisherUrl.
1987  *     \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating a socket.
1988  *     \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from 
1989  *             the publisher.
1990  *     \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused 
1991  *             the subscription request.
1992  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
1993  *             complete this operation.
1994  */
1995 EXPORT_SPEC int UpnpSubscribe(
1996         /*! [in] The handle of the control point. */
1997         UpnpClient_Handle Hnd,
1998         /*! [in] The URL of the service to subscribe to. */
1999         const char *PublisherUrl,
2000         /*! [in,out]Pointer to a variable containing the requested subscription time.
2001          * Upon return, it contains the actual subscription time returned from
2002          * the service. */
2003         int *TimeOut,
2004         /*! [out] Pointer to a variable to receive the subscription ID (SID). */
2005         Upnp_SID SubsId);
2006
2007
2008 /*!
2009  * \brief Performs the same operation as \b UpnpSubscribe, but returns
2010  * immediately and calls the registered callback function when the operation
2011  * is complete.
2012  *
2013  * Note that many of the error codes for this function are returned in
2014  * the \b UpnpEventSubscribe structure. In those cases, the function
2015  * returns \c UPNP_E_SUCCESS and the appropriate error code will
2016  * be in the <b>UpnpEventSubscribe.ErrCode</b> field in the \b Event
2017  * structure passed to the callback.
2018  *
2019  *  \return An integer representing one of the following:
2020  *      \li \c UPNP_E_SUCCESS: The operation completed successfully.
2021  *      \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
2022  *              point handle.
2023  *      \li \c UPNP_E_INVALID_URL: The \b PublisherUrl is not a valid 
2024  *              URL.
2025  *      \li \c UPNP_E_INVALID_PARAM: Either \b TimeOut or \b Fun or 
2026  *              \b PublisherUrl is not a valid pointer.
2027  *      \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
2028  *              complete this operation.
2029  *      \li \c UPNP_E_NETWORK_ERROR: A network error occured (returned in 
2030  *              the <b>UpnpEventSubscribe.ErrCode</b> field as part of the 
2031  *              callback).
2032  *      \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
2033  *              to a socket (returned in the 
2034  *              <b>UpnpEventSubscribe.ErrCode</b> field as part of the 
2035  *              callback).
2036  *      \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
2037  *              from a socket (returned in the 
2038  *              <b>UpnpEventSubscribe.ErrCode</b> field as part of the 
2039  *              callback).
2040  *      \li \c UPNP_E_SOCKET_BIND: An error occurred binding the socket 
2041  *              (returned in the <b>UpnpEventSubscribe.ErrCode</b> field as 
2042  *              part of the callback).
2043  *      \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to 
2044  *              \b PublisherUrl (returned in the \b 
2045  *              UpnpEventSubscribe.ErrCode field as part of the callback).
2046  *      \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating  the 
2047  *              socket (returned in the <b>UpnpEventSubscribe.ErrCode</b> 
2048  *              field as part of the callback).
2049  *      \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from 
2050  *              the publisher (returned in the \b 
2051  *              UpnpEventSubscribe.ErrCode field as part of the callback).
2052  *      \li \c UPNP_E_SUBSCRIBE_UNACCEPTED: The publisher refused 
2053  *              the subscription request (returned in the \b 
2054  *              UpnpEventSubscribe.ErrCode field as part of the callback).
2055  */
2056 EXPORT_SPEC int UpnpSubscribeAsync(
2057         /*! The handle of the control point that is subscribing. */
2058         UpnpClient_Handle Hnd,
2059         /*! The URL of the service to subscribe to. */
2060         const char *PublisherUrl,
2061         /*! The requested subscription time. Upon return, it contains the actual
2062          * subscription time returned from the service. */
2063         int TimeOut,
2064         /*! Pointer to the callback function for this subscribe request. */
2065         Upnp_FunPtr Fun,
2066         /*! A user data value passed to the callback function when invoked. */
2067         const void *Cookie);
2068
2069
2070 /*!
2071  * \brief Removes the subscription of a control point from a service previously
2072  * subscribed to using \b UpnpSubscribe or \b UpnpSubscribeAsync.
2073  *
2074  * This is a synchronous call.
2075  *
2076  * \return An integer representing one of the following:
2077  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
2078  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
2079  *             point handle.
2080  *     \li \c UPNP_E_INVALID_SID: The \b SubsId is not a valid 
2081  *             subscription ID.
2082  *     \li \c UPNP_E_NETWORK_ERROR: A network error occured. 
2083  *     \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
2084  *             to a socket.
2085  *     \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
2086  *             from a socket.
2087  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
2088  *     \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to 
2089  *             \b PublisherUrl.
2090  *     \li \c UPNP_E_OUTOF_SOCKET: An error ocurred creating a socket.
2091  *     \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from 
2092  *             the publisher.
2093  *     \li \c UPNP_E_UNSUBSCRIBE_UNACCEPTED: The publisher refused 
2094  *             the unsubscribe request (the client is still unsubscribed and 
2095  *             no longer receives events).
2096  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
2097  *             complete this operation.
2098  */
2099 EXPORT_SPEC int UpnpUnSubscribe(
2100         /*! [in] The handle of the subscribed control point. */
2101         UpnpClient_Handle Hnd,
2102         /*! [in] The ID returned when the control point subscribed to the service. */
2103         const Upnp_SID SubsId);
2104
2105
2106 /*!
2107  * \brief Removes a subscription of a control point from a service previously
2108  * subscribed to using \b UpnpSubscribe or \b UpnpSubscribeAsync, generating
2109  * a callback when the operation is complete.
2110  *
2111  * Note that many of the error codes for this function are returned in
2112  * the \b UpnpEventSubscribe structure.  In those cases, the function
2113  * returns \c UPNP_E_SUCCESS and the appropriate error code will
2114  * be in the <b>UpnpEventSubscribe.ErrCode</b> field in the \b Event
2115  * structure passed to the callback.
2116  *
2117  * \return An integer representing one of the following:
2118  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
2119  *     \li \c UPNP_E_INVALID_HANDLE: The handle is not a valid control 
2120  *             point handle.
2121  *     \li \c UPNP_E_INVALID_SID: The \b SubsId is not a valid SID.
2122  *     \li \c UPNP_E_INVALID_PARAM: \b Fun is not a valid callback 
2123  *             function pointer.
2124  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
2125  *             complete this operation.
2126  *     \li \c UPNP_E_NETWORK_ERROR: A network error occured (returned in 
2127  *             the <b>UpnpEventSubscribe.ErrCode</b> field as part of the 
2128  *             callback).
2129  *     \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
2130  *             to a socket (returned in the <b>UpnpEventSubscribe.ErrCode</b>
2131  *             field as part of the callback).
2132  *     \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
2133  *             from a socket (returned in the 
2134  *             <b>UpnpEventSubscribe.ErrCode</b> field as part of the 
2135  *             callback).
2136  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding the socket 
2137  *             (returned in the <b>UpnpEventSubscribe.ErrCode</b> field as 
2138  *             part of the callback).
2139  *     \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting to 
2140  *             \b PublisherUrl (returned in the <b>UpnpEventSubscribe.ErrCode</b>
2141  *             field as part of the callback).
2142  *     \li \c UPNP_E_OUTOF_SOCKET: An error occurred creating a socket (
2143  *             returned in the <b>UpnpEventSubscribe.ErrCode</b> field as 
2144  *             part of the callback).
2145  *     \li \c UPNP_E_BAD_RESPONSE: An error occurred in response from 
2146  *             the publisher (returned in the <b>UpnpEventSubscribe.ErrCode</b>
2147  *             field as part of the callback).
2148  *     \li \c UPNP_E_UNSUBSCRIBE_UNACCEPTED: The publisher refused 
2149  *             the subscription request (returned in the
2150  *             <b>UpnpEventSubscribe.ErrCode</b> field as part of the callback).
2151  */
2152 EXPORT_SPEC int UpnpUnSubscribeAsync(
2153         /*! [in] The handle of the subscribed control point. */
2154         UpnpClient_Handle Hnd,
2155         /*! [in] The ID returned when the control point subscribed to the service. */
2156         Upnp_SID SubsId,
2157         /*! [in] Pointer to a callback function to be called when the operation is
2158          * complete. */
2159         Upnp_FunPtr Fun,
2160         /*! [in] Pointer to user data to pass to the callback function when invoked. */
2161         const void *Cookie);
2162
2163
2164 /*! @} Eventing */
2165
2166
2167
2168 /******************************************************************************
2169  ******************************************************************************
2170  *                                                                            *
2171  *                        C L I E N T - A P I                                 *
2172  *                                                                            *
2173  ******************************************************************************
2174  ******************************************************************************/
2175
2176 /*!
2177  * \name Control Point HTTP API
2178  *
2179  * @{
2180  */
2181
2182 /*!
2183  * \brief Downloads a file specified in a URL.
2184  *
2185  * The SDK allocates the memory for \b outBuf and the application is
2186  * responsible for freeing this memory. Note that the item is passed as a
2187  * single buffer. Large items should not be transferred using this function.
2188  *
2189  *  \return An integer representing one of the following:
2190  *      \li \c UPNP_E_SUCCESS: The operation completed successfully.
2191  *      \li \c UPNP_E_INVALID_PARAM: Either \b url, \b outBuf 
2192  *              or \b contentType is not a valid pointer.
2193  *      \li \c UPNP_E_INVALID_URL: The \b url is not a valid 
2194  *              URL.
2195  *      \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
2196  *              download this file.
2197  *      \li \c UPNP_E_NETWORK_ERROR: A network error occurred.
2198  *      \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
2199  *              to a socket.
2200  *      \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
2201  *              from a socket.
2202  *      \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
2203  *      \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a 
2204  *              socket.
2205  *      \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently 
2206  *              allocated.
2207  */
2208 EXPORT_SPEC int UpnpDownloadUrlItem(
2209         /*! [in] URL of an item to download. */
2210         const char *url,
2211         /*! [out] Buffer to store the downloaded item. */
2212         char **outBuf,
2213         /*! [out] HTTP header value content type if present. It should be at least
2214          * \c LINE_SIZE bytes in size. */
2215         char *contentType);
2216
2217
2218 /*!
2219  * \brief Gets a file specified in a URL.
2220  *
2221  * The SDK allocates the memory for \b handle and \b contentType, the
2222  * application is responsible for freeing this memory.
2223  *
2224  * \return An integer representing one of the following:
2225  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
2226  *     \li \c UPNP_E_INVALID_PARAM: Either \b url, \b handle,  
2227  *             \b contentType, \b contentLength or \b httpStatus 
2228  *      is not a valid pointer.
2229  *     \li \c UPNP_E_INVALID_URL: The \b url is not a valid 
2230  *             URL.
2231  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
2232  *             download this file.
2233  *     \li \c UPNP_E_NETWORK_ERROR: A network error occurred.
2234  *     \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
2235  *             to a socket.
2236  *     \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
2237  *             from a socket.
2238  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
2239  *     \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a 
2240  *             socket.
2241  *     \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently 
2242  *             allocated.
2243  *     \li \c UPNP_E_BAD_RESPONSE: A bad response was received from the 
2244  *             remote server.
2245  */
2246 EXPORT_SPEC int UpnpOpenHttpGet(
2247         /*! [in] The URL of an item to get. */
2248         const char *url,
2249         /*! [in,out] A pointer to store the handle for this connection. */
2250         void **handle,
2251         /*! [in,out] A buffer to store the media type of the item. */
2252         char **contentType,
2253         /*! [in,out] A pointer to store the length of the item. */
2254         int *contentLength,
2255         /*! [in,out] The status returned on receiving a response message. */
2256         int *httpStatus,
2257         /*! [in] The time out value sent with the request during which a response
2258          * is expected from the server, failing which, an error is reported
2259          * back to the user. */          
2260         int timeout);
2261
2262
2263 /*!
2264  * \brief Gets a file specified in a URL through the specified proxy.
2265  *
2266  * The SDK allocates the memory for \b handle and \b contentType, the
2267  * application is responsible for freeing this memory.
2268  *
2269  * \return An integer representing one of the following:
2270  *     \li \c UPNP_E_SUCCESS: The operation completed successfully.
2271  *     \li \c UPNP_E_INVALID_PARAM: Either \b url, \b handle,  
2272  *             \b contentType, \b contentLength or \b httpStatus 
2273  *      is not a valid pointer.
2274  *     \li \c UPNP_E_INVALID_URL: The \b url is not a valid 
2275  *             URL.
2276  *     \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
2277  *             download this file.
2278  *     \li \c UPNP_E_NETWORK_ERROR: A network error occurred.
2279  *     \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
2280  *             to a socket.
2281  *     \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
2282  *             from a socket.
2283  *     \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
2284  *     \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a 
2285  *             socket.
2286  *     \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently 
2287  *             allocated.
2288  *     \li \c UPNP_E_BAD_RESPONSE: A bad response was received from the 
2289  *             remote server.
2290  */
2291 EXPORT_SPEC int UpnpOpenHttpGetProxy(
2292         /*! [in] The URL of an item to get. */
2293         const char *url,
2294         /*! [in] The URL of the proxy. */
2295         const char *proxy_str,
2296         /*! [in,out] A pointer to store the handle for this connection. */
2297         void **handle,
2298         /*! [in,out] A buffer to store the media type of the item. */
2299         char **contentType,
2300         /*! [in,out] A pointer to store the length of the item. */
2301         int *contentLength,
2302         /*! [in,out] The status returned on receiving a response message. */
2303         int *httpStatus,
2304         /*! [in] The time out value sent with the request during which a response
2305          * is expected from the server, failing which, an error is reported
2306          * back to the user. */          
2307         int timeout);
2308
2309
2310 /*!
2311  * \brief Gets specified number of bytes from a file specified in the URL.
2312  *
2313  * The number of bytes is specified through a low count and a high count which
2314  * are passed as a range of bytes for the request. The SDK allocates the memory
2315  * for \b handle and \b contentType, the application is responsible for freeing
2316  * this memory.
2317  *
2318  *  \return An integer representing one of the following:
2319  *      \li \c UPNP_E_SUCCESS: The operation completed successfully.
2320  *      \li \c UPNP_E_INVALID_PARAM: Either \b url, \b handle,  
2321  *              \b contentType, \b contentLength or \b httpStatus 
2322  *              is not a valid pointer.
2323  *      \li \c UPNP_E_INVALID_URL: The \b url is not a valid 
2324  *              URL.
2325  *      \li \c UPNP_E_OUTOF_MEMORY: Insufficient resources exist to 
2326  *              download this file.
2327  *      \li \c UPNP_E_NETWORK_ERROR: A network error occurred.
2328  *      \li \c UPNP_E_SOCKET_WRITE: An error or timeout occurred writing 
2329  *              to a socket.
2330  *      \li \c UPNP_E_SOCKET_READ: An error or timeout occurred reading 
2331  *              from a socket.
2332  *      \li \c UPNP_E_SOCKET_BIND: An error occurred binding a socket.
2333  *      \li \c UPNP_E_SOCKET_CONNECT: An error occurred connecting a 
2334  *              socket.
2335  *      \li \c UPNP_E_OUTOF_SOCKET: Too many sockets are currently 
2336  *              allocated.
2337  *      \li \c UPNP_E_BAD_RESPONSE: A bad response was received from the 
2338  *              remote server.
2339  */
2340 EXPORT_SPEC int UpnpOpenHttpGetEx(
2341         /*! [in] The URL of the item to get. */
2342         const char *url,
2343         /*! [in,out] A pointer to store the handle for this connection. */
2344         void **handle,
2345         /*! [in,out] A buffer to store the media type of the item. */
2346         char **contentType,
2347         /*! [in,out] A buffer to store the length of the item. */
2348         int *contentLength,
2349         /*! [in,out] The status returned on receiving a response message from the remote server. */
2350         int *httpStatus,
2351         /*! [in] An integer value representing the low end of a range to retrieve. */
2352         int lowRange,
2353         /*! [in] An integer value representing the high end of a range to retrieve. */
2354         int highRange,
2355         /*! [in] A time out value sent with the request during which a response is
2356          * expected from the server, failing which, an error is reported back
2357          * to the user. */      
2358         int timeout);
2359
2360