« back to all changes in this revision
Viewing changes to tombupnp/upnp/inc/upnp.h
- browse files at revision 1
- compare with another revision
- download diff
- download tarball
- view history from revision 1
- Committer: Bazaar Package Importer
- Author(s): Andres Mejia
- Date: 2008-02-02 01:42:48 UTC
- Revision ID: james.westby@ubuntu.com-20080202014248-cjouolddb8gi2zkz
Tags: upstream-0.10.0.dfsg1
Import upstream version 0.10.0.dfsg1
- files added:
- build
- config
- configure_aux
- doc
- scripts
- scripts/js
- src
- src/hash
- src/layout
- src/md5
- src/metadata
- src/mxml
- src/scripting
- src/storage
- src/storage/mysql
- src/storage/sqlite3
- src/uuid
- src/web
- src/zmm
- src/zmmf
- tombupnp
- tombupnp/build
- tombupnp/ixml
- tombupnp/ixml/inc
- tombupnp/ixml/src
- tombupnp/ixml/src/inc
- tombupnp/threadutil
- tombupnp/threadutil/inc
- tombupnp/threadutil/src
- tombupnp/upnp
- tombupnp/upnp/inc
- tombupnp/upnp/src
- tombupnp/upnp/src/api
- tombupnp/upnp/src/gena
- tombupnp/upnp/src/genlib
- tombupnp/upnp/src/genlib/client_table
- tombupnp/upnp/src/genlib/miniserver
- tombupnp/upnp/src/genlib/net
- tombupnp/upnp/src/genlib/net/http
- tombupnp/upnp/src/genlib/net/uri
- tombupnp/upnp/src/genlib/service_table
- tombupnp/upnp/src/genlib/util
- tombupnp/upnp/src/inc
- tombupnp/upnp/src/soap
- tombupnp/upnp/src/ssdp
- tombupnp/upnp/src/urlconfig
- tombupnp/upnp/src/uuid
- web
- web/icons
- web/icons/nanotree
- web/icons/nanotree/images
- web/js
added
removed
tombupnp/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
/*TU*
32
33
TombUPnP - a library for developing UPnP applications.
34
35
Copyright (C) 2006-2007 Sergey 'Jin' Bostandzhyan <jin@mediatomb.cc>
36
37
This library is free software; you can redistribute it and/or
38
modify it under the terms of the GNU Lesser General Public
39
License version 2.1 as published by the Free Software Foundation.
40
41
This library is distributed in the hope that it will be useful,
42
but WITHOUT ANY WARRANTY; without even the implied warranty of
43
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
44
Lesser General Public License for more details.
45
46
You should have received a copy of the GNU Lesser General Public
47
License along with this library; if not, write to the Free Software
48
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
49
*/
50
51
#ifndef UPNP_H
52
#define UPNP_H
53
54
/** @name The API */
55
56
//@{
57
58
#include <stdio.h>
59
#if defined(__FreeBSD__) || defined(__APPLE__)
60
#include <time.h>
61
#include <sys/types.h>
62
#endif
63
#include "ixml.h"
64
#include "upnpconfig.h"
65
#if UPNP_HAVE_DEBUG
66
# include "upnpdebug.h"
67
#endif
68
69
#ifdef WIN32
70
#ifndef UPNP_STATIC_LIB
71
#ifdef LIBUPNP_EXPORTS
72
// set up declspec for dll export to make functions visible to library users
73
#define EXPORT_SPEC __declspec(dllexport)
74
#else
75
#define EXPORT_SPEC __declspec(dllimport)
76
#endif
77
#else
78
#define EXPORT_SPEC
79
#endif
80
#else
81
#define EXPORT_SPEC
82
#endif
83
84
#ifndef WIN32
85
#define UpnpCloseSocket close
86
#else
87
#define UpnpCloseSocket closesocket
88
#endif
89
#define UPNP_SOCKETERROR -1
90
#define UPNP_INVALID_SOCKET -1
91
#ifndef WIN32
92
#define SOCKET int
93
#endif
94
95
#ifndef WIN32
96
#include <netinet/in.h>
97
#else
98
#include <winsock2.h>
99
#include <time.h>
100
#endif
101
102
#define NUM_HANDLE 200
103
#define LINE_SIZE 180
104
#define NAME_SIZE 256
105
#define HEADER_SIZE 256
106
#define MNFT_NAME_SIZE 64
107
#define MODL_NAME_SIZE 32
108
#define SERL_NUMR_SIZE 64
109
#define MODL_DESC_SIZE 64
110
#define UPNP_INFINITE -1
111
112
#define UPNP_USING_CHUNKED -3
113
#define UPNP_UNTIL_CLOSE -4
114
115
116
/** @name Error codes
117
* The functions in the SDK API can return a variety of error
118
* codes to describe problems encountered during execution. This section
119
* lists the error codes and provides a brief description of what each error
120
* code means. Refer to the documentation for each function for a
121
* description of what an error code means in that context.
122
*/
123
//@{
124
125
/** @name UPNP_E_SUCCESS [0]
126
* {\tt UPNP_E_SUCCESS} signifies that the operation completed successfully.
127
* For asynchronous functions, this only means that the packet generated by
128
* the operation was successfully transmitted on the network. The result of
129
* the entire operation comes as part of the callback for that operation.
130
*/
131
//@{
132
#define UPNP_E_SUCCESS 0
133
//@}
134
135
/** @name UPNP_E_INVALID_HANDLE [-100]
136
* {\tt UPNP_E_INVALID_HANDLE} signifies that the handle passed to a
137
* function is not a recognized as a valid handle.
138
*/
139
//@{
140
#define UPNP_E_INVALID_HANDLE -100
141
//@}
142
143
/** @name UPNP_E_INVALID_PARAM [-101]
144
* {\tt UPNP_E_INVALID_PARAM} signifies that one or more of the parameters
145
* passed to the function is not valid. Refer to the documentation for each
146
* function for more information on the valid ranges of the parameters.
147
*/
148
//@{
149
#define UPNP_E_INVALID_PARAM -101
150
//@}
151
152
/** @name UPNP_E_OUTOF_HANDLE [-102]
153
* {\tt UPNP_E_OUTOF_HANDLE} signifies that the SDK does not have any
154
* more space for additional handles. The SDK allocates space for only
155
* a few handles in order to conserve memory.
156
*/
157
//@{
158
#define UPNP_E_OUTOF_HANDLE -102
159
//@}
160
161
#define UPNP_E_OUTOF_CONTEXT -103
162
163
/** @name UPNP_E_OUTOF_MEMORY [-104]
164
* {\tt UPNP_E_OUTOF_MEMORY} signifies that not enough resources are
165
* currently available to complete the operation. Most operations require
166
* some free memory in order to complete their work.
167
*/
168
//@{
169
#define UPNP_E_OUTOF_MEMORY -104
170
//@}
171
172
/** @name UPNP_E_INIT [-105]
173
* {\tt UPNP_E_INIT} signifies that the SDK has already been
174
* initialized. The SDK needs to be initialied only once per process.
175
* Any additional initialization attempts simply return this error with
176
* no other ill effects.
177
*/
178
//@{
179
#define UPNP_E_INIT -105
180
//@}
181
182
#define UPNP_E_BUFFER_TOO_SMALL -106
183
184
/** @name UPNP_E_INVALID_DESC [-107]
185
* {\tt UPNP_E_INVALID_DESC} signifies that the description document passed
186
* to {\bf UpnpRegisterRootDevice} or {\bf UpnpRegisterRootDevice2} is an
187
* invalid description document.
188
*/
189
//@{
190
#define UPNP_E_INVALID_DESC -107
191
//@}
192
193
/** @name UPNP_E_INVALID_URL [-108]
194
* {\tt UPNP_E_INVALID_URL} signifies that a URL passed into the function
195
* is invalid. The actual cause is function specific, but in general, the
196
* URL itself might be malformed (e.g. have invalid characters in it) or
197
* the host might be unreachable.
198
*/
199
//@{
200
#define UPNP_E_INVALID_URL -108
201
//@}
202
203
#define UPNP_E_INVALID_SID -109
204
#define UPNP_E_INVALID_DEVICE -110
205
206
/** @name UPNP_E_INVALID_SERVICE [-111]
207
* {\tt UPNP_E_INVALID_SERVICE} is returned only by {\bf UpnpNotify},
208
* {\bf UpnpNotifyExt}, {\bf UpnpAcceptSubscription}, and
209
* {\bf UpnpAcceptSubscriptionExt} to signify that the device ID/service
210
* ID pair does not refer to a valid service.
211
*/
212
//@{
213
#define UPNP_E_INVALID_SERVICE -111
214
//@}
215
216
/** @name UPNP_E_BAD_RESPONSE [-113]
217
* {\tt UPNP_E_BAD_RESPONSE} signifies that the response received from the
218
* remote side of a connection is not correct for the protocol. This applies
219
* to the GENA, SOAP, and HTTP protocols.
220
*/
221
//@{
222
#define UPNP_E_BAD_RESPONSE -113
223
//@}
224
225
#define UPNP_E_BAD_REQUEST -114
226
227
/** @name UPNP_E_INVALID_ACTION [-115]
228
* {\tt UPNP_E_INVALID_ACTION} signifies that the SOAP action message is
229
* invalid. This can be because the DOM document passed to the function was
230
* malformed or the action message is not correct for the given action.
231
*/
232
//@{
233
#define UPNP_E_INVALID_ACTION -115
234
//@}
235
236
/** @name UPNP_E_FINISH [-116]
237
* {\tt UPNP_E_FINISH} signifies that {\bf UpnpInit} has not been called, or
238
* that {\bf UpnpFinish} has already been called. None of the API functions
239
* operate until {\bf UpnpInit} successfully completes.
240
*/
241
//@{
242
#define UPNP_E_FINISH -116
243
//@}
244
245
/** @name UPNP_E_INIT_FAILED [-117]
246
* {\tt UPNP_E_INIT_FAILED} signifies that {\bf UpnpInit} cannot complete.
247
* The typical reason is failure to allocate sufficient resources.
248
*/
249
//@{
250
#define UPNP_E_INIT_FAILED -117
251
//@}
252
253
/** @name UPNP_E_URL_TOO_BIG [-118]
254
* {\tt UPNP_E_URL_TOO_BIG} signifies that the URL passed into a function
255
* is too long. The SDK limits URLs to 180 characters in length.
256
*/
257
#define UPNP_E_URL_TOO_BIG -118
258
259
/** @name UPNP_E_BAD_HTTPMSG [-119]
260
* {\tt UPNP_E_BAD_HTTPMSG} signifies that the HTTP message contains invalid
261
* message headers. The error always refers to the HTTP message header
262
* received from the remote host. The main areas where this occurs are in
263
* SOAP control messages (e.g. {\bf UpnpSendAction}), GENA subscription
264
* message (e.g. {\bf UpnpSubscribe}), GENA event notifications (e.g. {\bf
265
* UpnpNotify}), and HTTP transfers (e.g. {\bf UpnpDownloadXmlDoc}).
266
*/
267
//@{
268
#define UPNP_E_BAD_HTTPMSG -119
269
//@}
270
271
/** @name UPNP_E_ALREADY_REGISTERED [-120]
272
* {\tt UPNP_E_ALREADY_REGISTERED} signifies that a client or a device is
273
* already registered. The SDK currently has a limit of one registered
274
* client and one registered device per process.
275
*/
276
//@{
277
#define UPNP_E_ALREADY_REGISTERED -120
278
//@}
279
280
/** @name UPNP_E_NETWORK_ERROR [-200]
281
* {\tt UPNP_E_NETWORK_ERROR} signifies that a network error occurred. It
282
* is the generic error code for network problems that are not covered under
283
* one of the more specific error codes. The typical meaning is the SDK
284
* failed to read the local IP address or had problems configuring one of
285
* the sockets.
286
*/
287
//@{
288
#define UPNP_E_NETWORK_ERROR -200
289
//@}
290
291
/** @name UPNP_E_SOCKET_WRITE [-201]
292
* {\tt UPNP_E_SOCKET_WRITE} signifies an error writing to a socket. This
293
* occurs in any function that makes network connections, such
294
* as discovery (e.g. {\bf UpnpSearchAsync} or {\bf UpnpSendAdvertisement}),
295
* control (e.g. {\bf UpnpSendAction}), eventing (e.g. {\bf UpnpNotify}),
296
* and HTTP functions (e.g. {\bf UpnpDownloadXmlDoc}).
297
*/
298
//@{
299
#define UPNP_E_SOCKET_WRITE -201
300
//@}
301
302
/** @name UPNP_E_SOCKET_READ [-202]
303
* {\tt UPNP_E_SOCKET_READ} signifies an error reading from a socket. This
304
* occurs in any function that makes network connections, such
305
* as discovery (e.g. {\bf UpnpSearchAsync} or {\bf UpnpSendAdvertisement}),
306
* control (e.g. {\bf UpnpSendAction}), eventing (e.g. {\bf UpnpNotify}),
307
* and HTTP functions (e.g. {\bf UpnpDownloadXmlDoc}).
308
*/
309
//@{
310
#define UPNP_E_SOCKET_READ -202
311
//@}
312
313
/** @name UPNP_E_SOCKET_BIND [-203]
314
* {\tt UPNP_E_SOCKET_BIND} signifies that the SDK had a problem binding
315
* a socket to a network interface. This occurs in any function that makes
316
* network connections, such as discovery (e.g. {\bf UpnpSearchAsync} or
317
* {\bf UpnpSendAdvertisement}), control (e.g. {\bf UpnpSendAction}), eventing
318
* (e.g. {\bf UpnpNotify}), and HTTP functions (e.g.
319
* {\bf UpnpDownloadXmlDoc}).
320
*/
321
//@{
322
#define UPNP_E_SOCKET_BIND -203
323
//@}
324
325
/** @name UPNP_E_SOCKET_CONNECT [-204]
326
* {\tt UPNP_E_SOCKET_CONNECT} signifies that the SDK had a problem
327
* connecting to a remote host. This occurs in any function that makes
328
* network connections, such as discovery (e.g. {\bf UpnpSearchAsync} or
329
* {\bf UpnpSendAdvertisement}), control (e.g. {\bf UpnpSendAction}), eventing
330
* (e.g. {\bf UpnpNotify}), and HTTP functions (e.g.
331
* {\bf UpnpDownloadXmlDoc}).
332
*/
333
//@{
334
#define UPNP_E_SOCKET_CONNECT -204
335
//@}
336
337
/** @name UPNP_E_OUTOF_SOCKET [-205]
338
* {\tt UPNP_E_OUTOF_SOCKET} signifies that the SDK cannot create any
339
* more sockets. This occurs in any function that makes
340
* network connections, such as discovery (e.g. {\bf UpnpSearchAsync} or
341
* {\bf UpnpSendAdvertisement}), control (e.g. {\bf UpnpSendAction}), eventing
342
* (e.g. {\bf UpnpNotify}), and HTTP functions (e.g.
343
* {\bf UpnpDownloadXmlDoc}).
344
*/
345
//@{
346
#define UPNP_E_OUTOF_SOCKET -205
347
//@}
348
349
/** @name UPNP_E_LISTEN [-206]
350
* {\tt UPNP_E_LISTEN} signifies that the SDK had a problem setting the
351
* socket to listen for incoming connections. This error only happens during
352
* initialization (i.e. {\bf UpnpInit}).
353
*/
354
//@{
355
#define UPNP_E_LISTEN -206
356
//@}
357
358
/** @name UPNP_E_TIMEDOUT [-207]
359
* {\tt UPNP_E_TIMEDOUT} signifies that too much time elapsed before the
360
* required number of bytes were sent or received over a socket. This error
361
* can be returned by any function that performs network operations.
362
*/
363
//@{
364
#define UPNP_E_TIMEDOUT -207
365
//@}
366
367
/** @name UPNP_E_SOCKET_ERROR [-208]
368
* {\tt UPNP_E_SOCKET_ERROR} is the generic socket error code for
369
* conditions not covered by other error codes. This error can be returned
370
* by any function that performs network operations.
371
*/
372
//@{
373
#define UPNP_E_SOCKET_ERROR -208
374
//@}
375
376
#define UPNP_E_FILE_WRITE_ERROR -209
377
378
/** @name UPNP_E_CANCELED [-210]
379
* {\tt UPNP_E_CANCELED} signifies that the operation was canceled. This
380
* error can be returned by any function that allows for external
381
* cancelation.
382
*/
383
//@{
384
#define UPNP_E_CANCELED -210
385
//@}
386
387
#define UPNP_E_EVENT_PROTOCOL -300
388
389
/** @name UPNP_E_SUBSCRIBE_UNACCEPTED [-301]
390
* {\tt UPNP_E_SUBSCRIBE_UNACCEPTED} signifies that a subscription
391
* request was rejected from the remote side.
392
*/
393
//@{
394
#define UPNP_E_SUBSCRIBE_UNACCEPTED -301
395
//@}
396
397
/** @name UPNP_E_UNSUBSCRIBE_UNACCAPTED [-302]
398
* {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED} signifies that an unsubscribe
399
* request was rejected from the remote side.
400
*/
401
//@{
402
#define UPNP_E_UNSUBSCRIBE_UNACCEPTED -302
403
//@}
404
405
/** @name UPNP_E_NOTIFY_UNACCEPTED [-303]
406
* {\tt UPNP_E_NOTIFY_UNACCEPTED} signifies that the remote host did not
407
* accept the notify sent from the local device.
408
*/
409
//@{
410
#define UPNP_E_NOTIFY_UNACCEPTED -303
411
//@}
412
413
/** @name UPNP_E_INVALID_ARGUMENT [-501]
414
* {\tt UPNP_E_INVALID_ARGUMENT} signifies that one or more of the parameters
415
* passed to a function is invalid. Refer to the individual function
416
* descriptions for the acceptable ranges for parameters.
417
*/
418
//@{
419
#define UPNP_E_INVALID_ARGUMENT -501
420
//@}
421
422
/** @name UPNP_E_FILE_NOT_FOUND [-502]
423
* {\tt UPNP_E_FILE_NOT_FOUND} signifies that the filename passed
424
* to one of the device registration functions was not found or was not
425
* accessible.
426
*/
427
//@{
428
#define UPNP_E_FILE_NOT_FOUND -502
429
//@}
430
431
/** @name UPNP_E_FILE_READ_ERROR [-503]
432
* {\tt UPNP_E_FILE_READ_ERROR} signifies an error when reading a file.
433
*/
434
//@{
435
#define UPNP_E_FILE_READ_ERROR -503
436
//@}
437
438
/** @name UPNP_E_EXT_NOT_XML [-504]
439
* {\tt UPNP_E_EXT_NOT_XML} signifies that the file name of the description
440
* document passed to {\bf UpnpRegisterRootDevice2} does not end in ".xml".
441
*/
442
//@{
443
#define UPNP_E_EXT_NOT_XML -504
444
//@}
445
446
#define UPNP_E_NO_WEB_SERVER -505
447
#define UPNP_E_OUTOF_BOUNDS -506
448
449
/** @name UPNP_E_NOT_FOUND [-507]
450
* {\tt UPNP_E_NOT_FOUND} signifies that the response to a SOAP request
451
* did not contain the required XML constructs.
452
*/
453
//@{
454
#define UPNP_E_NOT_FOUND -507
455
//@}
456
457
/** @name UPNP_E_INTERNAL_ERROR [-911]
458
* {\tt UPNP_E_INTERNAL_ERROR} is the generic error code for internal
459
* conditions not covered by other error codes.
460
*/
461
//@{
462
#define UPNP_E_INTERNAL_ERROR -911
463
//@}
464
465
// SOAP-related error codes
466
#define UPNP_SOAP_E_INVALID_ACTION 401
467
#define UPNP_SOAP_E_INVALID_ARGS 402
468
#define UPNP_SOAP_E_OUT_OF_SYNC 403
469
#define UPNP_SOAP_E_INVALID_VAR 404
470
#define UPNP_SOAP_E_ACTION_FAILED 501
471
472
//@}
473
474
#ifndef OUT
475
#define OUT
476
#endif
477
478
#ifndef IN
479
#define IN
480
#endif
481
482
#ifndef INOUT
483
#define INOUT
484
#endif
485
486
enum UpnpOpenFileMode{UPNP_READ, UPNP_WRITE};
487
488
/// @name Constants, Structures, and Types
489
//@{
490
491
/** Returned when a control point application registers with {\bf
492
* UpnpRegisterClient}. Client handles can only be used with
493
* functions that operate with a client handle. */
494
495
typedef int UpnpClient_Handle;
496
497
/** Returned when a device application registers with {\bf
498
* UpnpRegisterRootDevice} or {\bf UpnpRegisterRootDevice2}. Device handles
499
* can only be used with functions that operate with a device handle. */
500
501
typedef int UpnpDevice_Handle;
502
503
/** @name UPnP_EventType
504
@memo The reason code for an event callback.
505
@doc The {\bf Event} parameter will be different depending on the
506
reason for the callback. The descriptions for each event
507
type describe the contents of the {\bf Event} parameter.
508
*/
509
510
enum Upnp_EventType_e {
511
512
//
513
// Control callbacks
514
//
515
516
/** Received by a device when a control point issues a control
517
* request. The {\bf Event} parameter contains a pointer to a {\bf
518
* Upnp_Action_Request} structure containing the action. The application
519
* stores the results of the action in this structure. */
520
521
UPNP_CONTROL_ACTION_REQUEST,
522
523
/** A {\bf UpnpSendActionAsync} call completed. The {\bf Event}
524
* parameter contains a pointer to a {\bf Upnp_Action_Complete} structure
525
* with the results of the action. */
526
527
UPNP_CONTROL_ACTION_COMPLETE,
528
529
/** Received by a device when a query for a single service variable
530
* arrives. The {\bf Event} parameter contains a pointer to a {\bf
531
* Upnp_State_Var_Request} structure containing the name of the variable
532
* and value. */
533
534
UPNP_CONTROL_GET_VAR_REQUEST,
535
536
/** A {\bf UpnpGetServiceVarStatus} call completed. The {\bf Event}
537
* parameter contains a pointer to a {\bf Upnp_State_Var_Complete} structure
538
* containing the value for the variable. */
539
540
UPNP_CONTROL_GET_VAR_COMPLETE,
541
542
//
543
// Discovery callbacks
544
//
545
546
/** Received by a control point when a new device or service is available.
547
* The {\bf Event} parameter contains a pointer to a {\bf
548
* Upnp_Discovery} structure with the information about the device
549
* or service. */
550
551
UPNP_DISCOVERY_ADVERTISEMENT_ALIVE,
552
553
/** Received by a control point when a device or service shuts down. The {\bf
554
* Event} parameter contains a pointer to a {\bf Upnp_Discovery}
555
* structure containing the information about the device or
556
* service. */
557
558
UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE,
559
560
/** Received by a control point when a matching device or service responds.
561
* The {\bf Event} parameter contains a pointer to a {\bf
562
* Upnp_Discovery} structure containing the information about
563
* the reply to the search request. */
564
565
UPNP_DISCOVERY_SEARCH_RESULT,
566
567
/** Received by a control point when the search timeout expires. The
568
* SDK generates no more callbacks for this search after this
569
* event. The {\bf Event} parameter is {\tt NULL}. */
570
571
UPNP_DISCOVERY_SEARCH_TIMEOUT,
572
573
//
574
// Eventing callbacks
575
//
576
577
/** Received by a device when a subscription arrives.
578
* The {\bf Event} parameter contains a pointer to a {\bf
579
* Upnp_Subscription_Request} structure. At this point, the
580
* subscription has already been accepted. {\bf UpnpAcceptSubscription}
581
* needs to be called to confirm the subscription and transmit the
582
* initial state table. This can be done during this callback. The SDK
583
* generates no events for a subscription unless the device
584
* application calls {\bf UpnpAcceptSubscription}.
585
*/
586
587
UPNP_EVENT_SUBSCRIPTION_REQUEST,
588
589
/** Received by a control point when an event arrives. The {\bf
590
* Event} parameter contains a {\bf Upnp_Event} structure
591
* with the information about the event. */
592
593
UPNP_EVENT_RECEIVED,
594
595
/** A {\bf UpnpRenewSubscriptionAsync} call completed. The status of
596
* the renewal is in the {\bf Event} parameter as a {\bf
597
* Upnp_Event_Subscription} structure. */
598
599
UPNP_EVENT_RENEWAL_COMPLETE,
600
601
/** A {\bf UpnpSubscribeAsync} call completed. The status of the
602
* subscription is in the {\bf Event} parameter as a {\bf
603
* Upnp_Event_Subscription} structure. */
604
605
UPNP_EVENT_SUBSCRIBE_COMPLETE,
606
607
/** A {\bf UpnpUnSubscribeAsync} call completed. The status of the
608
* subscription is in the {\bf Event} parameter as a {\bf
609
* Upnp_Event_Subscribe} structure. */
610
611
UPNP_EVENT_UNSUBSCRIBE_COMPLETE,
612
613
/** The auto-renewal of a client subscription failed.
614
* The {\bf Event} parameter is a {\bf Upnp_Event_Subscribe} structure
615
* with the error code set appropriately. The subscription is no longer
616
* valid. */
617
618
UPNP_EVENT_AUTORENEWAL_FAILED,
619
620
/** A client subscription has expired. This will only occur
621
* if auto-renewal of subscriptions is disabled.
622
* The {\bf Event} parameter is a {\bf Upnp_Event_Subscribe}
623
* structure. The subscription is no longer valid. */
624
625
UPNP_EVENT_SUBSCRIPTION_EXPIRED
626
627
};
628
629
typedef enum Upnp_EventType_e Upnp_EventType;
630
631
/** The {\bf Upnp_SID} holds the subscription identifier for a subscription
632
between a client and a device. The SID is a string representation of
633
a globally unique id (GUID) and should not be modified.
634
*/
635
636
typedef char Upnp_SID[44];
637
638
/** @name Upnp_SType
639
@memo Represents the different types of searches that
640
can be performed using the SDK for UPnP Devices API.
641
@doc By specifying these different values to
642
{\bf UpnpSearchAsync}, the control point application
643
can control the scope of the search from all devices
644
to specific devices or services.
645
*/
646
647
enum Upnp_SType_e {
648
649
/** Search for all devices and services on the network. */
650
UPNP_S_ALL,
651
652
/** Search for all root devices on the network. */
653
UPNP_S_ROOT,
654
655
/** Search for a particular device type or a particular device
656
instance. */
657
UPNP_S_DEVICE,
658
659
/** Search for a particular service type, possibly on a particular
660
* device type or device instance. */
661
UPNP_S_SERVICE
662
663
};
664
665
typedef enum Upnp_SType_e Upnp_SType;
666
667
/** @name Upnp_DescType
668
@memo Specifies the type of description in
669
{\bf UpnpRegisterRootDevice2}.
670
@doc These values control how {\bf UpnpRegisterRootDevice2}
671
interprets the {\bf description} parameter.
672
*/
673
enum Upnp_DescType_e {
674
675
/** The description is the URL to the description document. */
676
UPNPREG_URL_DESC,
677
678
/** The description is a file name on the local file system
679
containing the description of the device. */
680
UPNPREG_FILENAME_DESC,
681
682
/** The description is a pointer to a character array containing
683
the XML description document. */
684
UPNPREG_BUF_DESC
685
686
};
687
688
typedef enum Upnp_DescType_e Upnp_DescType;
689
690
/** Returned as part of a {\bf UPNP_CONTROL_ACTION_COMPLETE} callback. */
691
692
struct Upnp_Action_Request
693
{
694
/** The result of the operation. */
695
int ErrCode;
696
697
/** The socket number of the connection to the requestor. */
698
int Socket;
699
700
/** The error string in case of error. */
701
char ErrStr[LINE_SIZE];
702
703
/** The Action Name. */
704
char ActionName[NAME_SIZE];
705
706
/** The unique device ID. */
707
char DevUDN[NAME_SIZE];
708
709
/** The service ID. */
710
char ServiceID[NAME_SIZE];
711
712
/** The DOM document describing the action. */
713
IXML_Document *ActionRequest;
714
715
/** The DOM document describing the result of the action. */
716
IXML_Document *ActionResult;
717
718
/** IP address of the control point requesting this action. */
719
struct in_addr CtrlPtIPAddr;
720
721
/** The DOM document containing the information from the
722
the SOAP header. */
723
IXML_Document *SoapHeader;
724
};
725
726
struct Upnp_Action_Complete
727
{
728
/** The result of the operation. */
729
int ErrCode;
730
731
/** The control URL for service. */
732
char CtrlUrl[NAME_SIZE];
733
734
/** The DOM document describing the action. */
735
IXML_Document *ActionRequest;
736
737
/** The DOM document describing the result of the action. */
738
IXML_Document *ActionResult;
739
740
};
741
742
/** Represents the request for current value of a state variable in a service
743
* state table. */
744
745
struct Upnp_State_Var_Request
746
{
747
/** The result of the operation. */
748
int ErrCode;
749
750
/** The socket number of the connection to the requestor. */
751
int Socket;
752
753
/** The error string in case of error. */
754
char ErrStr[LINE_SIZE];
755
756
/** The unique device ID. */
757
char DevUDN[NAME_SIZE];
758
759
/** The service ID. */
760
char ServiceID[NAME_SIZE];
761
762
/** The name of the variable. */
763
char StateVarName[NAME_SIZE];
764
765
/** IP address of sender requesting the state variable. */
766
struct in_addr CtrlPtIPAddr;
767
768
/** The current value of the variable. This needs to be allocated by
769
* the caller. When finished with it, the SDK frees this {\bf DOMString}. */
770
DOMString CurrentVal;
771
};
772
773
/** Represents the reply for the current value of a state variable in an
774
asynchronous call. */
775
776
struct Upnp_State_Var_Complete
777
{
778
/** The result of the operation. */
779
int ErrCode;
780
781
/** The control URL for the service. */
782
char CtrlUrl[NAME_SIZE];
783
784
/** The name of the variable. */
785
char StateVarName[NAME_SIZE];
786
787
/** The current value of the variable or error string in case of error. */
788
DOMString CurrentVal;
789
};
790
791
/** Returned along with a {\bf UPNP_EVENT_RECEIVED} callback. */
792
793
struct Upnp_Event
794
{
795
/** The subscription ID for this subscription. */
796
Upnp_SID Sid;
797
798
/** The event sequence number. */
799
int EventKey;
800
801
/** The DOM tree representing the changes generating the event. */
802
IXML_Document *ChangedVariables;
803
804
};
805
806
//
807
// This typedef is required by Doc++ to parse the last entry of the
808
// Upnp_Discovery structure correctly.
809
//
810
811
typedef struct sockaddr_in SOCKADDRIN;
812
813
/** Returned in a {\bf UPNP_DISCOVERY_RESULT} callback. */
814
815
struct Upnp_Discovery
816
{
817
818
/** The result code of the {\bf UpnpSearchAsync} call. */
819
int ErrCode;
820
821
/** The expiration time of the advertisement. */
822
int Expires;
823
824
/** The unique device identifier. */
825
char DeviceId[LINE_SIZE];
826
827
/** The device type. */
828
char DeviceType[LINE_SIZE];
829
830
/** The service type. */
831
char ServiceType[LINE_SIZE];
832
833
/** The service version. */
834
char ServiceVer[LINE_SIZE];
835
836
/** The URL to the UPnP description document for the device. */
837
char Location[LINE_SIZE];
838
839
/** The operating system the device is running. */
840
char Os[LINE_SIZE];
841
842
/** Date when the response was generated. */
843
char Date[LINE_SIZE];
844
845
/** Confirmation that the MAN header was understood by the device. */
846
char Ext[LINE_SIZE];
847
848
/** The host address of the device responding to the search. */
849
SOCKADDRIN * DestAddr;
850
851
};
852
853
/** Returned along with a {\bf UPNP_EVENT_SUBSCRIBE_COMPLETE} or {\bf
854
* UPNP_EVENT_UNSUBSCRIBE_COMPLETE} callback. */
855
856
struct Upnp_Event_Subscribe {
857
858
/** The SID for this subscription. For subscriptions, this only
859
* contains a valid SID if the {\bf Upnp_EventSubscribe.result} field
860
* contains a {\tt UPNP_E_SUCCESS} result code. For unsubscriptions,
861
* this contains the SID from which the subscription is being
862
* unsubscribed. */
863
864
Upnp_SID Sid;
865
866
/** The result of the operation. */
867
int ErrCode;
868
869
/** The event URL being subscribed to or removed from. */
870
char PublisherUrl[NAME_SIZE];
871
872
/** The actual subscription time (for subscriptions only). */
873
int TimeOut;
874
875
};
876
877
/** Returned along with a {\bf UPNP_EVENT_SUBSCRIPTION_REQUEST}
878
* callback. */
879
880
struct Upnp_Subscription_Request
881
{
882
/** The identifier for the service being subscribed to. */
883
char *ServiceId;
884
885
/** Universal device name. */
886
char *UDN;
887
888
/** The assigned subscription ID for this subscription. */
889
Upnp_SID Sid;
890
891
};
892
893
894
struct File_Info
895
{
896
/** The length of the file. A length less than 0 indicates the size
897
* is unknown, and data will be sent until 0 bytes are returned from
898
* a read call. */
899
off_t file_length;
900
901
/** The time at which the contents of the file was modified;
902
* The time system is always local (not GMT). */
903
time_t last_modified;
904
905
/** If the file is a directory, {\bf is_directory} contains
906
* a non-zero value. For a regular file, it should be 0. */
907
int is_directory;
908
909
/** If the file or directory is readable, this contains
910
* a non-zero value. If unreadable, it should be set to 0. */
911
int is_readable;
912
913
/** The content type of the file. This string needs to be allocated
914
* by the caller using {\bf ixmlCloneDOMString}. When finished
915
* with it, the SDK frees the {\bf DOMString}. */
916
DOMString content_type;
917
918
/** A header to be added to the HTTP response. The header will be
919
* automatically terminated with \r\n by the SDK. This string needs
920
* to be allocated by the caller using {\bf ixmlCloneDOMString}.
921
* When finished with it, the SDK frees the {\bf DOMString}. */
922
DOMString http_header;
923
924
};
925
926
/* The type of handle returned by the web server for open requests. */
927
928
typedef void *UpnpWebFileHandle;
929
930
/** The {\bf UpnpVirtualDirCallbacks} structure contains the pointers to
931
* file-related callback functions a device application can register to
932
* virtualize URLs.
933
*/
934
struct UpnpVirtualDirCallbacks
935
{
936
/** Called by the web server to query information on a file. The callback
937
* should return 0 on success or -1 on an error. */
938
int (*get_info) (
939
IN const char *filename, /** The name of the file to query. */
940
OUT struct File_Info *info /** Pointer to a structure to store the
941
information on the file. */
942
);
943
944
/** Called by the web server to open a file. The callback should return
945
* a valid handle if the file can be opened. Otherwise, it should return
946
* {\tt NULL} to signify an error. */
947
UpnpWebFileHandle (*open)(
948
IN const char *filename, /** The name of the file to open. */
949
OUT struct File_Info *info, /** Pointer to a structure to store the
950
information on the file. */
951
IN enum UpnpOpenFileMode Mode /** The mode in which to open the file.
952
Valid values are {\tt UPNP_READ} or
953
{\tt UPNP_WRITE}. */
954
);
955
956
/** Called by the web server to perform a sequential read from an open
957
* file. The callback should copy {\bf buflen} bytes from the file into
958
* the buffer.
959
* @return [int] An integer representing one of the following:
960
* \begin{itemize}
961
* \item {\tt 0}: The file contains no more data (EOF).
962
* \item {\tt >0}: A successful read of the number of bytes in the
963
* return code.
964
* \item {\tt <0}: An error occurred reading the file.
965
* \end{itemzie}
966
*/
967
int (*read) (
968
IN UpnpWebFileHandle fileHnd, /** The handle of the file to read. */
969
OUT char *buf, /** The buffer in which to place the
970
data. */
971
IN size_t buflen /** The size of the buffer (i.e. the
972
number of bytes to read). */
973
);
974
975
/** Called by the web server to perform a sequential write to an open
976
* file. The callback should write {\bf buflen} bytes into the file from
977
* the buffer. It should return the actual number of bytes written,
978
* which might be less than {\bf buflen} in the case of a write error.
979
*/
980
int (*write) (
981
IN UpnpWebFileHandle fileHnd, /** The handle of the file to write. */
982
IN char *buf, /** The buffer with the bytes to write. */
983
IN size_t buflen /** The number of bytes to write. */
984
);
985
986
/** Called by the web server to move the file pointer, or offset, into
987
* an open file. The {\bf origin} parameter determines where to start
988
* moving the file pointer. A value of {\tt SEEK_CUR} moves the
989
* file pointer relative to where it is. The {\bf offset} parameter can
990
* be either positive (move forward) or negative (move backward).
991
* {\tt SEEK_END} moves relative to the end of the file. A positive
992
* {\bf offset} extends the file. A negative {\bf offset} moves backward
993
* in the file. Finally, {\tt SEEK_SET} moves to an absolute position in
994
* the file. In this case, {\bf offset} must be positive. The callback
995
* should return 0 on a successful seek or a non-zero value on an error.
996
*/
997
int (*seek) (
998
IN UpnpWebFileHandle fileHnd, /** The handle of the file to move the
999
file pointer. */
1000
IN off_t offset, /** The number of bytes to move in the
1001
file. Positive values move foward and
1002
negative values move backward. Note
1003
that this must be positive if the
1004
{\bf origin} is {\tt SEEK_SET}. */
1005
IN int origin /** The position to move relative to. It
1006
can be {\tt SEEK_CUR} to move relative
1007
to the current position,
1008
{\tt SEEK_END} to move relative to
1009
the end of the file, or {\tt
1010
SEEK_SET} to specify an absolute
1011
offset. */
1012
);
1013
1014
/** Called by the web server to close a file opened via the {\bf open}
1015
* callback. It should return 0 on success, or a non-zero value on an
1016
* error.
1017
*/
1018
int (*close) (
1019
IN UpnpWebFileHandle fileHnd /** The handle of the file to close. */
1020
);
1021
1022
};
1023
1024
typedef struct virtual_Dir_List
1025
{
1026
struct virtual_Dir_List *next;
1027
char dirName[NAME_SIZE];
1028
} virtualDirList;
1029
1030
typedef struct user_HTTP_Header_List
1031
{
1032
struct user_HTTP_Header_List *next;
1033
char header[HEADER_SIZE];
1034
} userHTTPHeaderList;
1035
1036
1037
/** All callback functions share the same prototype, documented below.
1038
* Note that any memory passed to the callback function
1039
* is valid only during the callback and should be copied if it
1040
* needs to persist. This callback function needs to be thread
1041
* safe. The context of the callback is always on a valid thread
1042
* context and standard synchronization methods can be used. Note,
1043
* however, because of this the callback cannot call SDK functions
1044
* unless explicitly noted.
1045
*
1046
* \begin{verbatim}
1047
int CallbackFxn( Upnp_EventType EventType, void* Event, void* Cookie );
1048
\end{verbatim}
1049
*
1050
* where {\bf EventType} is the event that triggered the callback,
1051
* {\bf Event} is a structure that denotes event-specific information for that
1052
* event, and {\bf Cookie} is the user data passed when the callback was
1053
* registered.
1054
*
1055
* See {\bf Upnp_EventType} for more information on the callback values and
1056
* the associated {\bf Event} parameter.
1057
*
1058
* The return value of the callback is currently ignored. It may be used
1059
* in the future to communicate results back to the SDK.
1060
*/
1061
1062
typedef int (*Upnp_FunPtr) (
1063
IN Upnp_EventType EventType,
1064
IN void *Event,
1065
IN void *Cookie
1066
);
1067
1068
//@} // Constants, Structures, and Types
1069
1070
#ifdef __cplusplus
1071
extern "C" {
1072
#endif // __cplusplus
1073
1074
///@name Initialization and Registration
1075
//@{
1076
/** Initializes the Linux SDK for UPnP Devices. This function must be called
1077
* before any other API function can be called. It should be called
1078
* only once. Subsequent calls to this API return a {\tt UPNP_E_INIT}
1079
* error code.
1080
*
1081
* Optionally, the application can specify a host IP address (in the
1082
* case of a multi-homed configuration) and a port number to use for
1083
* all UPnP operations. Since a port number can be used only by one
1084
* process, multiple processes using the SDK must specify
1085
* different port numbers.
1086
*
1087
* If unspecified, the SDK will use the first adapter's IP address
1088
* and an arbitrary port.
1089
*
1090
* This call is synchronous.
1091
*
1092
* @return [int] An integer representing one of the following:
1093
* \begin{itemize}
1094
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1095
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist
1096
* to initialize the SDK.
1097
* \item {\tt UPNP_E_INIT}: The SDK is already initialized.
1098
* \item {\tt UPNP_E_INIT_FAILED}: The SDK initialization
1099
* failed for an unknown reason.
1100
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
1101
* \item {\tt UPNP_E_LISTEN}: An error occurred listening to a socket.
1102
* \item {\tt UPNP_E_OUTOF_SOCKET}: An error ocurred creating a socket.
1103
* \item {\tt UPNP_E_INTERNAL_ERROR}: An internal error ocurred.
1104
* \end{itemize} */
1105
1106
EXPORT_SPEC int UpnpInit(
1107
IN const char *HostIP, /** The host IP address to use, in
1108
string format, for example "192.168.0.1",
1109
or {\tt NULL} to use the first adapter's
1110
IP address. */
1111
IN unsigned short DestPort, /** The destination port number to use. 0
1112
will pick an arbitrary free port. */
1113
IN int maxHTTPTimeoutRetries, /** maximum number of retries when select
1114
times out on sending data, use a
1115
negative value to disable this feature **/
1116
IN void *thread_cleanup /** A user defined callback function that
1117
will get triggered each time a thread dies
1118
(only for threads that were calling other
1119
user callbacks). We need this to allow
1120
extra cleanup, for example for MySQL */
1121
);
1122
1123
/** Terminates the Linux SDK for UPnP Devices. This function must be the last
1124
* API function called. It should be called only once. Subsequent calls to
1125
* this API return a {\tt UPNP_E_FINISH} error code.
1126
*
1127
* @return [int] An integer representing one of the following:
1128
* \begin{itemize}
1129
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1130
* \item {\tt UPNP_E_FINISH}: The SDK is already terminated or
1131
* it is not initialized.
1132
* \end{itemize} */
1133
1134
EXPORT_SPEC int UpnpFinish();
1135
1136
/** If '0' is used as the port number in {\bf UpnpInit}, then this
1137
* function can be used to retrieve the actual port allocated to
1138
* the SDK. If {\bf UpnpInit} has not succeeded then 0 is
1139
* returned.
1140
*
1141
* @return [unsigned short] The port on which an internal server is
1142
* listening for UPnP related requests.
1143
*/
1144
EXPORT_SPEC unsigned short UpnpGetServerPort(void);
1145
1146
/** If {\tt NULL} is used as the IP address in {\bf UpnpInit}, then this
1147
* function can be used to retrieve the actual interface address
1148
* on which device is running. If {\bf UpnpInit} has not succeeded
1149
* then {\tt NULL} is returned.
1150
*
1151
* @return [char*] The IP address on which an internal server is listening
1152
* for UPnP related requests.
1153
*/
1154
EXPORT_SPEC char * UpnpGetServerIpAddress(void);
1155
1156
/** {\bf UpnpRegisterClient} registers a control point application with the
1157
* SDK. A control point application cannot make any other API calls
1158
* until it registers using this function.
1159
*
1160
* {\bf UpnpRegisterClient} is a synchronous call and generates no callbacks.
1161
* Callbacks can occur as soon as this function returns.
1162
*
1163
* @return [int] An integer representing one of the following:
1164
* \begin{itemize}
1165
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1166
* \item {\tt UPNP_E_FINISH}: The SDK is already terminated or
1167
* is not initialized.
1168
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd}
1169
* is not a valid pointer.
1170
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1171
* register this control point.
1172
* \end{itemize}
1173
*/
1174
1175
EXPORT_SPEC int UpnpRegisterClient(
1176
IN Upnp_FunPtr Callback, /** Pointer to a function for receiving
1177
asynchronous events. */
1178
IN const void *Cookie, /** Pointer to user data returned with the
1179
callback function when invoked. */
1180
OUT UpnpClient_Handle *Hnd /** Pointer to a variable to store the
1181
new control point handle. */
1182
);
1183
1184
/** {\bf UpnpRegisterRootDevice} registers a device application with
1185
* the SDK. A device application cannot make any other API
1186
* calls until it registers using this function. Device applications
1187
* can also register as control points (see {\bf UpnpRegisterClient}
1188
* to get a control point handle to perform control point
1189
* functionality).
1190
*
1191
* {\bf UpnpRegisterRootDevice} is synchronous and does not generate
1192
* any callbacks. Callbacks can occur as soon as this function returns.
1193
*
1194
* @return [int] An integer representing one of the following:
1195
* \begin{itemize}
1196
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1197
* \item {\tt UPNP_E_FINISH}: The SDK is already terminated or
1198
* is not initialized.
1199
* \item {\tt UPNP_E_INVALID_DESC}: The description document was not
1200
* a valid device description.
1201
* \item {\tt UPNP_E_INVALID_URL}: The URL for the description document
1202
* is not valid.
1203
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd}
1204
* is not a valid pointer or {\bf DescURL} is {\tt NULL}.
1205
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred.
1206
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
1207
* to a socket.
1208
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
1209
* from a socket.
1210
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
1211
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting the
1212
* socket.
1213
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
1214
* allocated.
1215
* \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to
1216
* register this root device.
1217
* \end{itemize} */
1218
1219
EXPORT_SPEC int UpnpRegisterRootDevice(
1220
IN const char *DescUrl, /** Pointer to a string containing the
1221
description URL for this root device
1222
instance. */
1223
IN Upnp_FunPtr Callback, /** Pointer to the callback function for
1224
receiving asynchronous events. */
1225
IN const void *Cookie, /** Pointer to user data returned with the
1226
callback function when invoked. */
1227
OUT UpnpDevice_Handle *Hnd /** Pointer to a variable to store the
1228
new device handle. */
1229
);
1230
1231
/** {\bf UpnpRegisterRootDevice2} is similar to {\bf UpnpRegisterRootDevice},
1232
* except that it also allows the description document to be specified as a
1233
* file or a memory buffer. The description can also be configured to have the
1234
* correct IP and port address.
1235
*
1236
* NOTE: For the configuration to be functional, the internal web server
1237
* MUST be present. In addition, the web server MUST be activated
1238
* (using {\bf UpnpSetWebServerRootDir}) before calling this function.
1239
* The only condition where the web server can be absent is if the
1240
* description document is specified as a URL and no configuration is
1241
* required (i.e. {\tt config_baseURL = 0}.)
1242
*
1243
* {\bf UpnpRegisterRootDevice2} is synchronous and does not generate
1244
* any callbacks. Callbacks can occur as soon as this function returns.
1245
*
1246
* Examples of using different types of description documents:
1247
* \begin{verbatim}
1248
1) Description specified as a URL:
1249
descriptionType == UPNPREG_URL_DESC
1250
description is the URL
1251
bufferLen = 0 (ignored)
1252
2) Description specified as a file:
1253
descriptionType == UPNPREG_FILENAME_DESC
1254
description is a filename
1255
bufferLen = 0 (ignored)
1256
3) Description specified as a memory buffer:
1257
descriptionType == UPNPREG_BUF_DESC
1258
description is pointer to a memory buffer
1259
bufferLen == length of memory buffer
1260
\end{verbatim}
1261
*
1262
* @return [int] An integer representing one of the following:
1263
* \begin{itemize}
1264
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1265
* \item {\tt UPNP_E_FINISH}: The SDK is already terminated or
1266
* is not initialized.
1267
* \item {\tt UPNP_E_INVALID_DESC}: The description document is not
1268
* a valid device description.
1269
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Callback} or {\bf Hnd}
1270
* is not a valid pointer or {\bf DescURL} is {\tt NULL}.
1271
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred.
1272
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
1273
* to a socket.
1274
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
1275
* from a socket.
1276
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
1277
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting the
1278
* socket.
1279
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
1280
* allocated.
1281
* \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to
1282
* register this root device.
1283
* \item {\tt UPNP_E_URL_TOO_BIG}: Length of the URL is bigger than the
1284
* internal buffer.
1285
* \item {\tt UPNP_E_FILE_NOT_FOUND}: The description file could not
1286
* be found.
1287
* \item {\tt UPNP_E_FILE_READ_ERROR}: An error occurred reading the
1288
* description file.
1289
* \item {\tt UPNP_E_INVALID_URL}: The URL to the description document
1290
* is invalid.
1291
* \item {\tt UPNP_E_EXT_NOT_XML}: The URL to the description document
1292
* or file should have a {\tt .xml} extension.
1293
* \item {\tt UPNP_E_NO_WEB_SERVER}: The internal web server has been
1294
* compiled out; the SDK cannot configure itself from the
1295
* description document.
1296
* \end{itemize} */
1297
1298
EXPORT_SPEC int UpnpRegisterRootDevice2(
1299
IN Upnp_DescType descriptionType,/** The type of the description
1300
document. */
1301
IN const char* description, /** Treated as a URL, file name or
1302
memory buffer depending on
1303
description type. */
1304
IN size_t bufferLen, /** The length of memory buffer if
1305
passing a description in a buffer,
1306
otherwise it is ignored. */
1307
IN int config_baseURL, /** If nonzero, {\tt URLBase} of
1308
description document is
1309
configured and the description
1310
is served using the internal
1311
web server. */
1312
IN Upnp_FunPtr Fun, /** Pointer to the callback function
1313
for receiving asynchronous
1314
events. */
1315
IN const void* Cookie, /** Pointer to user data returned
1316
with the callback function when
1317
invoked. */
1318
OUT UpnpDevice_Handle* Hnd /** Pointer to a variable to store
1319
the new device handle. */
1320
);
1321
1322
/** {\bf UpnpUnRegisterClient} unregisters a control point application,
1323
* unsubscribing all active subscriptions. After this call, the
1324
* {\bf UpnpClient_Handle} is no longer valid.
1325
*
1326
* {\bf UpnpUnRegisterClient} is a synchronous call and generates no
1327
* callbacks. The SDK generates no more callbacks after this
1328
* function returns.
1329
*
1330
* @return [int] An integer representing one of the following:
1331
* \begin{itemize}
1332
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1333
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1334
* point handle.
1335
* \end{itemize} */
1336
1337
EXPORT_SPEC int UpnpUnRegisterClient(
1338
IN UpnpClient_Handle Hnd /** The handle of the control point instance
1339
to unregister. */
1340
);
1341
1342
/** Unregisters a root device registered with {\bf UpnpRegisterRootDevice} or
1343
* {\bf UpnpRegisterRootDevice2}. After this call, the
1344
* {\bf UpnpDevice_Handle} is no longer valid. For all advertisements that
1345
* have not yet expired, the SDK sends a device unavailable message
1346
* automatically.
1347
*
1348
* {\bf UpnpUnRegisterRootDevice} is a synchronous call and generates no
1349
* callbacks. Once this call returns, the SDK will no longer
1350
* generate callbacks to the application.
1351
*
1352
* @return [int] An integer representing one of the following:
1353
* \begin{itemize}
1354
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1355
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid
1356
* device handle.
1357
* \end{itemize}
1358
*/
1359
1360
EXPORT_SPEC int UpnpUnRegisterRootDevice(
1361
IN UpnpDevice_Handle /** The handle of the root device instance to
1362
unregister. */
1363
);
1364
1365
1366
/** OBSOLETE METHOD : use {\bf UpnpSetMaxContentLength} instead.
1367
* Warning: the Handle argument provided here is not used, so the effect
1368
* of this function is global to the SDK (= same as
1369
* {\bf UpnpSetMaxContentLength} ).
1370
*/
1371
EXPORT_SPEC int UpnpSetContentLength(
1372
IN UpnpClient_Handle Hnd,
1373
IN int contentLength
1374
);
1375
1376
1377
/** Sets the maximum content-length that the SDK will process on an incoming
1378
* SOAP requests or responses. This API allows devices that have memory
1379
* constraints to exhibit consistent behaviour if the size of the
1380
* incoming SOAP message exceeds the memory that device can allocate.
1381
* The default maximum content-length is {\tt DEFAULT_SOAP_CONTENT_LENGTH}
1382
* = 16K bytes.
1383
*
1384
* @return [int] An integer representing one of the following:
1385
* \begin{itemize}
1386
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1387
* \end{itemize}
1388
*/
1389
EXPORT_SPEC int UpnpSetMaxContentLength(
1390
IN size_t contentLength /** The maximum permissible content length
1391
for incoming SOAP actions, in bytes. */
1392
);
1393
1394
//@} // Initialization and Registration
1395
1396
////////////////////////////////////////////////////////////////////////
1397
////////////////////////////////////////////////////////////////////////
1398
// //
1399
// D I S C O V E R Y //
1400
// //
1401
////////////////////////////////////////////////////////////////////////
1402
////////////////////////////////////////////////////////////////////////
1403
1404
///@name Discovery
1405
//@{
1406
1407
/** {\bf UpnpSearchAsync} searches for devices matching the given
1408
* search target. The function returns immediately and the SDK
1409
* calls the default callback function, registered during the
1410
* {\bf UpnpRegisterClient} call, for each matching root device,
1411
* device, or service. The application specifies the search type by the
1412
* {\bf Target} parameter.
1413
*
1414
* Note that there is no way for the SDK to distinguish which client
1415
* instance issued a particular search. Therefore, the client can get
1416
* search callbacks that do not match the original criteria of the search.
1417
* Also, the application will receive multiple callbacks for each search.
1418
*
1419
* @return [int] An integer representing one of the following:
1420
* \begin{itemize}
1421
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1422
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1423
* point handle.
1424
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf Target} is {\tt NULL}.
1425
* \end{itemize} */
1426
1427
EXPORT_SPEC int UpnpSearchAsync(
1428
IN UpnpClient_Handle Hnd, /** The handle of the client performing
1429
the search. */
1430
IN int Mx, /** The time, in seconds, to wait for
1431
responses. If the time is greater
1432
than {\tt MAX_SEARCH_TIME} then the time is
1433
set to {\tt MAX_SEARCH_TIME}. If the time is
1434
less than {\tt MIN_SEARCH_TIME} then the
1435
time is set to {\tt MIN_SEARCH_TIME}. */
1436
IN const char *Target, /** The search target as defined in the UPnP
1437
Device Architecture v1.0 specification. */
1438
IN const void *Cookie /** The user data to pass when the callback
1439
function is invoked. */
1440
);
1441
1442
/** {\bf UpnpSendAdvertisement} sends out the discovery announcements for
1443
* all devices and services for a device. Each announcement is made with
1444
* the same expiration time.
1445
*
1446
* {\bf UpnpSendAdvertisement} is a synchronous call.
1447
*
1448
* @return [int] An integer representing one of the following:
1449
* \begin{itemize}
1450
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1451
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid
1452
* device handle.
1453
* \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to
1454
* send future advertisements.
1455
* \end{itemize}
1456
*/
1457
EXPORT_SPEC int UpnpSendAdvertisement(
1458
IN UpnpDevice_Handle Hnd, /** The device handle for which to send out the
1459
announcements. */
1460
IN int Exp /** The expiration age, in seconds, of
1461
the announcements. */
1462
);
1463
1464
//@} // Discovery
1465
1466
////////////////////////////////////////////////////////////////////////
1467
////////////////////////////////////////////////////////////////////////
1468
// //
1469
// C O N T R O L //
1470
// //
1471
////////////////////////////////////////////////////////////////////////
1472
////////////////////////////////////////////////////////////////////////
1473
1474
///@name Control
1475
//@{
1476
1477
/** {\bf UpnpGetServiceVarStatus} queries the state of a state
1478
* variable of a service on another device. This is a synchronous call.
1479
* A positive return value indicates a SOAP error code, whereas a negative
1480
* return code indicates an SDK error code. {\bf Note that the use of this
1481
* function is deprecated by the UPnP Forum}.
1482
*
1483
* @return [int] An integer representing one of the following:
1484
* \begin{itemize}
1485
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1486
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1487
* point handle.
1488
* \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL.
1489
* \item {\tt UPNP_E_INVALID_DESC}: The XML document was not
1490
* found or it does not contain a valid XML description.
1491
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf StVarVal} is not a valid
1492
* pointer or {\bf VarName} or {\bf ActionUrl} is {\tt NULL}.
1493
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1494
* complete this operation.
1495
* \item {\tt UPNP_SOAP_E_INVALID_VAR}: The given variable is invalid
1496
* according to the device.
1497
* \end{itemize}
1498
*/
1499
1500
EXPORT_SPEC int UpnpGetServiceVarStatus(
1501
IN UpnpClient_Handle Hnd, /** The handle of the control point. */
1502
IN const char *ActionURL, /** The URL of the service. */
1503
IN const char *VarName, /** The name of the variable to query. */
1504
OUT DOMString *StVarVal /** The pointer to store the value
1505
for {\bf VarName}. The SDK
1506
allocates this string and the caller
1507
needs to free it using
1508
{\bf ixmlFreeDOMString}. */
1509
);
1510
1511
/** {\bf UpnpGetServiceVarStatusAsync} queries the state of a variable of a
1512
* service, generating a callback when the operation is complete. {\bf Note
1513
* that the use of this function is deprecated by the UPnP Forum}.
1514
*
1515
* @return [int] An integer representing one of the following:
1516
* \begin{itemize}
1517
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1518
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1519
* point handle.
1520
* \item {\tt UPNP_E_INVALID_URL}: The {\bf ActionUrl} is not a valid URL.
1521
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf VarName}, {\bf Fun} or
1522
* {\bf ActionUrl} is not a valid pointer.
1523
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1524
* complete this operation.
1525
* \end{itemize}
1526
*/
1527
1528
EXPORT_SPEC int UpnpGetServiceVarStatusAsync(
1529
IN UpnpClient_Handle Hnd, /** The handle of the control point. */
1530
IN const char *ActionURL, /** The URL of the service. */
1531
IN const char *VarName, /** The name of the variable to query. */
1532
IN Upnp_FunPtr Fun, /** Pointer to a callback function to
1533
be invoked when the operation is complete. */
1534
IN const void *Cookie /** Pointer to user data to pass to the
1535
callback function when invoked. */
1536
);
1537
1538
/** {\bf UpnpSendAction} sends a message to change a state variable
1539
* in a service. This is a synchronous call that does not return until the
1540
* action is complete.
1541
*
1542
* Note that a positive return value indicates a SOAP-protocol error code.
1543
* In this case, the error description can be retrieved from {\bf RespNode}.
1544
* A negative return value indicates an SDK error.
1545
*
1546
* @return [int] An integer representing one of the following:
1547
* \begin{itemize}
1548
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1549
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1550
* point handle.
1551
* \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL.
1552
* \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid.
1553
* \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is not a
1554
* valid device.
1555
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf ServiceType}, {\bf Action},
1556
* {\bf ActionUrl}, or
1557
* {\bf RespNode} is not a valid pointer.
1558
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1559
* complete this operation.
1560
* \end{itemize}
1561
*/
1562
1563
EXPORT_SPEC int UpnpSendAction(
1564
IN UpnpClient_Handle Hnd, /** The handle of the control point
1565
sending the action. */
1566
IN const char *ActionURL, /** The action URL of the service. */
1567
IN const char *ServiceType, /** The type of the service. */
1568
IN const char *DevUDN, /** This parameter is ignored and must be
1569
{\tt NULL}. */
1570
IN IXML_Document *Action, /** The DOM document for the action. */
1571
OUT IXML_Document **RespNode /** The DOM document for the response
1572
to the action. The SDK allocates
1573
this document and the caller needs to free
1574
it. */
1575
);
1576
1577
/** {\bf UpnpSendActionEx} sends a message to change a state variable
1578
* in a service. This is a synchronous call that does not return until the
1579
* action is complete.
1580
*
1581
* Note that a positive return value indicates a SOAP-protocol error code.
1582
* In this case, the error description can be retrieved from {\bf RespNode}.
1583
* A negative return value indicates an SDK error.
1584
*
1585
* @return [int] An integer representing one of the following:
1586
* \begin{itemize}
1587
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1588
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1589
* point handle.
1590
* \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is not a valid URL.
1591
* \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid.
1592
* \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is not a
1593
* valid device.
1594
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf ServiceType}, {\bf Action},
1595
* {\bf ActionUrl}, or
1596
* {\bf RespNode} is not a valid pointer.
1597
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1598
* complete this operation.
1599
* \end{itemize}
1600
*/
1601
1602
EXPORT_SPEC int UpnpSendActionEx(
1603
IN UpnpClient_Handle Hnd, /** The handle of the control point
1604
sending the action. */
1605
IN const char *ActionURL, /** The action URL of the service. */
1606
IN const char *ServiceType, /** The type of the service. */
1607
IN const char *DevUDN, /** This parameter is ignored and must be
1608
{\tt NULL}. */
1609
IN IXML_Document *Header, /** The DOM document for the SOAP header.
1610
This may be {\tt NULL} if the header is
1611
not required. */
1612
IN IXML_Document *Action, /** The DOM document for the action. */
1613
OUT IXML_Document **RespNode /** The DOM document for the response
1614
to the action. The SDK allocates
1615
this document and the caller needs to free
1616
it. */
1617
);
1618
1619
/** {\bf UpnpSendActionAsync} sends a message to change a state variable
1620
* in a service, generating a callback when the operation is complete.
1621
* See {\bf UpnpSendAction} for comments on positive return values. These
1622
* positive return values are sent in the event struct associated with the
1623
* {\tt UPNP_CONTROL_ACTION_COMPLETE} event.
1624
*
1625
* @return [int] An integer representing one of the following:
1626
* \begin{itemize}
1627
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1628
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1629
* point handle.
1630
* \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is an invalid URL.
1631
* \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is an invalid device.
1632
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Fun} is not a valid
1633
* callback function or {\bf ServiceType}, {\bf Act}, or
1634
* {\bf ActionUrl} is {\tt NULL}.
1635
* \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid.
1636
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1637
* complete this operation.
1638
* \end{itemize}
1639
*/
1640
1641
EXPORT_SPEC int UpnpSendActionAsync(
1642
IN UpnpClient_Handle Hnd, /** The handle of the control point
1643
sending the action. */
1644
IN const char *ActionURL, /** The action URL of the service. */
1645
IN const char *ServiceType, /** The type of the service. */
1646
IN const char *DevUDN, /** This parameter is ignored and must be
1647
{\tt NULL}. */
1648
IN IXML_Document *Action, /** The DOM document for the action to
1649
perform on this device. */
1650
IN Upnp_FunPtr Fun, /** Pointer to a callback function to
1651
be invoked when the operation
1652
completes. */
1653
IN const void *Cookie /** Pointer to user data that to be
1654
passed to the callback when invoked. */
1655
);
1656
1657
/** {\bf UpnpSendActionExAsync} sends a message to change a state variable
1658
* in a service, generating a callback when the operation is complete.
1659
* See {\bf UpnpSendAction} for comments on positive return values. These
1660
* positive return values are sent in the event struct associated with the
1661
* {\tt UPNP_CONTROL_ACTION_COMPLETE} event.
1662
*
1663
* @return [int] An integer representing one of the following:
1664
* \begin{itemize}
1665
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1666
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1667
* point handle.
1668
* \item {\tt UPNP_E_INVALID_URL}: {\bf ActionUrl} is an invalid URL.
1669
* \item {\tt UPNP_E_INVALID_DEVICE}: {\bf DevUDN} is an invalid device.
1670
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Fun} is not a valid
1671
* callback function or {\bf ServiceType}, {\bf Act}, or
1672
* {\bf ActionUrl} is {\tt NULL}.
1673
* \item {\tt UPNP_E_INVALID_ACTION}: This action is not valid.
1674
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1675
* complete this operation.
1676
* \end{itemize}
1677
*/
1678
1679
EXPORT_SPEC int UpnpSendActionExAsync(
1680
IN UpnpClient_Handle Hnd, /** The handle of the control point
1681
sending the action. */
1682
IN const char *ActionURL, /** The action URL of the service. */
1683
IN const char *ServiceType, /** The type of the service. */
1684
IN const char *DevUDN, /** This parameter is ignored and must be
1685
{\tt NULL}. */
1686
IN IXML_Document *Header, /** The DOM document for the SOAP header.
1687
This may be {\tt NULL} if the header is
1688
not required. */
1689
IN IXML_Document *Action, /** The DOM document for the action to
1690
perform on this device. */
1691
IN Upnp_FunPtr Fun, /** Pointer to a callback function to
1692
be invoked when the operation
1693
completes. */
1694
IN const void *Cookie /** Pointer to user data that to be
1695
passed to the callback when invoked. */
1696
);
1697
1698
//@} // Control
1699
1700
////////////////////////////////////////////////////////////////////////
1701
////////////////////////////////////////////////////////////////////////
1702
// //
1703
// E V E N T I N G //
1704
// //
1705
////////////////////////////////////////////////////////////////////////
1706
////////////////////////////////////////////////////////////////////////
1707
1708
///@name Eventing
1709
//@{
1710
1711
/** {\bf UpnpAcceptSubscription} accepts a subscription request and sends
1712
* out the current state of the eventable variables for a service.
1713
* The device application should call this function when it receives a
1714
* {\tt UPNP_EVENT_SUBSCRIPTION_REQUEST} callback. This function is
1715
* synchronous and generates no callbacks.
1716
*
1717
* {\bf UpnpAcceptSubscription} can be called during the execution of
1718
* a callback function.
1719
*
1720
* @return [int] An integer representing one of the following:
1721
* \begin{itemize}
1722
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1723
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device
1724
* handle.
1725
* \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId}
1726
* pair refers to an invalid service.
1727
* \item {\tt UPNP_E_INVALID_SID}: The specified subscription ID is not
1728
* valid.
1729
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf VarName},
1730
* {\bf NewVal}, {\bf DevID}, or {\bf ServID} is not a valid
1731
* pointer or {\bf cVariables} is less than zero.
1732
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1733
* complete this operation.
1734
* \end{itemize}
1735
*/
1736
1737
EXPORT_SPEC int UpnpAcceptSubscription(
1738
IN UpnpDevice_Handle Hnd, /** The handle of the device. */
1739
IN const char *DevID, /** The device ID of the subdevice of the
1740
service generating the event. */
1741
IN const char *ServID, /** The unique service identifier of the service
1742
generating the event. */
1743
IN const char **VarName, /** Pointer to an array of event variables. */
1744
IN const char **NewVal, /** Pointer to an array of values for
1745
the event variables. */
1746
IN int cVariables, /** The number of event variables in
1747
{\bf VarName}. */
1748
IN Upnp_SID SubsId /** The subscription ID of the newly
1749
registered control point. */
1750
);
1751
1752
/** {\bf UpnpAcceptSubscriptionExt} is similar to {\bf UpnpAcceptSubscription}
1753
* except that it takes a DOM document for the variables to event rather
1754
* than an array of strings. This function is sychronous
1755
* and generates no callbacks.
1756
*
1757
* {\bf UpnpAcceptSubscriptionExt} can be called during the execution of
1758
* a callback function.
1759
*
1760
* @return [int] An integer representing one of the following:
1761
* \begin{itemize}
1762
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1763
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device
1764
* handle.
1765
* \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId}
1766
* pair refers to an invalid service.
1767
* \item {\tt UPNP_E_INVALID_SID}: The specified subscription ID is not
1768
* valid.
1769
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf VarName},
1770
* {\bf NewVal}, {\bf DevID}, {\bf ServID}, or {\bf PropSet}
1771
* is not a valid pointer.
1772
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1773
* complete this operation.
1774
* \end{itemize}
1775
*/
1776
1777
EXPORT_SPEC int UpnpAcceptSubscriptionExt(
1778
IN UpnpDevice_Handle Hnd, /** The handle of the device. */
1779
IN const char *DevID, /** The device ID of the subdevice of the
1780
service generating the event. */
1781
IN const char *ServID, /** The unique service identifier of the service
1782
generating the event. */
1783
IN IXML_Document *PropSet, /** The DOM document for the property set.
1784
Property set documents must conform to
1785
the XML schema defined in section 4.3 of the
1786
Universal Plug and Play Device Architecture
1787
specification. */
1788
IN Upnp_SID SubsId /** The subscription ID of the newly
1789
registered control point. */
1790
);
1791
1792
/** {\bf UpnpNotify} sends out an event change notification to all
1793
* control points subscribed to a particular service. This function is
1794
* synchronous and generates no callbacks.
1795
*
1796
* {\bf UpnpNotify} may be called during a callback function to send out
1797
* a notification.
1798
*
1799
* @return [int] An integer representing one of the following:
1800
* \begin{itemize}
1801
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1802
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device
1803
* handle.
1804
* \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId}
1805
* pair refers to an invalid service.
1806
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf VarName}, {\bf NewVal},
1807
* {\bf DevID}, or {\bf ServID} is not a valid pointer or
1808
* {\bf cVariables} is less than zero.
1809
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1810
* complete this operation.
1811
* \end{itemize}
1812
*/
1813
1814
EXPORT_SPEC int UpnpNotify(
1815
IN UpnpDevice_Handle, /** The handle to the device sending the event. */
1816
IN const char *DevID, /** The device ID of the subdevice of the service
1817
generating the event. */
1818
IN const char *ServID, /** The unique identifier of the service
1819
generating the event. */
1820
IN const char **VarName,/** Pointer to an array of variables that
1821
have changed. */
1822
IN const char **NewVal, /** Pointer to an array of new values for
1823
those variables. */
1824
IN int cVariables /** The count of variables included in this
1825
notification. */
1826
);
1827
1828
/** {\bf UpnpNotifyExt} is similar to {\bf UpnpNotify} except that it takes
1829
* a DOM document for the event rather than an array of strings. This
1830
* function is synchronous and generates no callbacks.
1831
*
1832
* {\bf UpnpNotifyExt} may be called during a callback function to send out
1833
* a notification.
1834
*
1835
* @return [int] An integer representing one of the following:
1836
* \begin{itemize}
1837
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1838
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device
1839
* handle.
1840
* \item {\tt UPNP_E_INVALID_SERVICE}: The {\bf DevId}/{\bf ServId}
1841
* pair refers to an invalid service.
1842
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf VarName}, {\bf NewVal},
1843
* {\bf DevID}, {\bf ServID}, or {\bf PropSet}
1844
* is not a valid pointer or {\bf cVariables} is less than zero.
1845
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1846
* complete this operation.
1847
* \end{itemize}
1848
*/
1849
1850
EXPORT_SPEC int UpnpNotifyExt(
1851
IN UpnpDevice_Handle, /** The handle to the device sending the
1852
event. */
1853
IN const char *DevID, /** The device ID of the subdevice of the
1854
service generating the event. */
1855
IN const char *ServID, /** The unique identifier of the service
1856
generating the event. */
1857
IN IXML_Document *PropSet /** The DOM document for the property set.
1858
Property set documents must conform to
1859
the XML schema defined in section 4.3 of
1860
the Universal Plug and Play Device
1861
Architecture specification. */
1862
);
1863
1864
/** {\bf UpnpRenewSubscription} renews a subscription that is about to
1865
* expire. This function is synchronous.
1866
*
1867
* @return [int] An integer representing one of the following:
1868
* \begin{itemize}
1869
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1870
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1871
* point handle.
1872
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf Timeout} is not a valid pointer.
1873
* \item {\tt UPNP_E_INVALID_SID}: The SID being passed to this function
1874
* is not a valid subscription ID.
1875
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured.
1876
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
1877
* to a socket.
1878
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
1879
* from a socket.
1880
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
1881
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to
1882
* {\bf PublisherUrl}.
1883
* \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating a socket.
1884
* \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from
1885
* the publisher.
1886
* \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused
1887
* the subscription renew.
1888
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1889
* complete this operation.
1890
* \end{itemize}
1891
*/
1892
1893
EXPORT_SPEC int UpnpRenewSubscription(
1894
IN UpnpClient_Handle Hnd, /** The handle of the control point that
1895
is renewing the subscription. */
1896
INOUT int *TimeOut, /** Pointer to a variable containing the
1897
requested subscription time. Upon return,
1898
it contains the actual renewal time. */
1899
IN Upnp_SID SubsId /** The ID for the subscription to renew. */
1900
);
1901
1902
/** {\bf UpnpRenewSubscriptionAsync} renews a subscription that is about
1903
* to expire, generating a callback when the operation is complete.
1904
*
1905
* Note that many of the error codes for this function are returned in
1906
* the {\bf Upnp_Event_Subscribe} structure. In those cases, the function
1907
* returns {\tt UPNP_E_SUCCESS} and the appropriate error code will
1908
* be in the {\bf Upnp_Event_Subscribe.ErrCode} field in the {\bf Event}
1909
* structure passed to the callback.
1910
*
1911
* @return [int] An integer representing one of the following:
1912
* \begin{itemize}
1913
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1914
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
1915
* point handle.
1916
* \item {\tt UPNP_E_INVALID_SID}: The {\bf SubsId} is not a valid
1917
* subscription ID.
1918
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf Fun} is not a valid
1919
* callback function pointer or {\bf Timeout} is less than zero
1920
* but is not {\tt UPNP_INFINITE}.
1921
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
1922
* complete this operation.
1923
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured (returned in
1924
* the {\bf Upnp_Event_Subscribe.ErrCode} field as part of the
1925
* callback).
1926
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
1927
* to a socket (returned in the {\bf Upnp_Event_Subscribe.ErrCode}
1928
* field as part of the callback).
1929
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
1930
* from a socket (returned in the
1931
* {\bf Upnp_Event_Subscribe.ErrCode} field as part of the
1932
* callback).
1933
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding the socket
1934
* (returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as
1935
* part of the callback).
1936
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to
1937
* {\bf PublisherUrl} (returned in the {\bf
1938
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
1939
* \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating socket (
1940
* returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as
1941
* part of the callback).
1942
* \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from
1943
* the publisher (returned in the {\bf
1944
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
1945
* \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused
1946
* the subscription request (returned in the {\bf
1947
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
1948
* \end{itemize}
1949
*/
1950
1951
EXPORT_SPEC int UpnpRenewSubscriptionAsync(
1952
IN UpnpClient_Handle Hnd, /** The handle of the control point that
1953
is renewing the subscription. */
1954
IN int TimeOut, /** The requested subscription time. The
1955
actual timeout value is returned when
1956
the callback function is called. */
1957
IN Upnp_SID SubsId, /** The ID for the subscription to renew. */
1958
IN Upnp_FunPtr Fun, /** Pointer to a callback function to be
1959
invoked when the renewal is complete. */
1960
IN const void *Cookie /** Pointer to user data passed
1961
to the callback function when invoked. */
1962
);
1963
1964
/** {\bf UpnpSetMaxSubscriptions} sets the maximum number of subscriptions
1965
* accepted per service. The default value accepts as many as system
1966
* resources allow. If the number of current subscriptions for a service is
1967
* greater than the requested value, the SDK accepts no new
1968
* subscriptions or renewals, however, the SDK does not remove
1969
* any current subscriptions.
1970
*
1971
* @return [int] An integer representing one of the following:
1972
* \begin{itemize}
1973
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1974
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device
1975
* handle.
1976
* \end{itemize}
1977
*/
1978
1979
EXPORT_SPEC int UpnpSetMaxSubscriptions(
1980
IN UpnpDevice_Handle Hnd, /** The handle of the device for which
1981
the maximum number of subscriptions is
1982
being set. */
1983
IN int MaxSubscriptions /** The maximum number of subscriptions to be
1984
allowed per service. */
1985
);
1986
1987
/** {\bf UpnpSetMaxSubscriptionTimeOut} sets the maximum time-out accepted
1988
* for a subscription request or renewal. The default value accepts the
1989
* time-out set by the control point. If a control point requests a
1990
* subscription time-out less than or equal to the maximum, the SDK
1991
* grants the value requested by the control point. If the time-out
1992
* is greater, the SDK returns the maximum value.
1993
*
1994
* @return [int] An integer representing one of the following:
1995
* \begin{itemize}
1996
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
1997
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid device
1998
* handle.
1999
* \end{itemize}
2000
*/
2001
2002
EXPORT_SPEC int UpnpSetMaxSubscriptionTimeOut(
2003
IN UpnpDevice_Handle Hnd, /** The handle of the device for which
2004
the maximum subscription time-out is
2005
being set. */
2006
IN int MaxSubscriptionTimeOut /** The maximum subscription time-out to
2007
be accepted. */
2008
);
2009
2010
/** {\bf UpnpSubscribe} registers a control point to receive event
2011
* notifications from another device. This operation is synchronous.
2012
*
2013
* @return [int] An integer representing one of the following:
2014
* \begin{itemize}
2015
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2016
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
2017
* point handle.
2018
* \item {\tt UPNP_E_INVALID_URL}: {\bf PublisherUrl} is not a valid URL.
2019
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf Timeout} is not a valid pointer
2020
* or {\bf SubsId} or {\bf PublisherUrl} is {\tt NULL}.
2021
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured.
2022
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2023
* to a socket.
2024
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2025
* from a socket.
2026
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
2027
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to
2028
* {\bf PublisherUrl}.
2029
* \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating a socket.
2030
* \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from
2031
* the publisher.
2032
* \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused
2033
* the subscription request.
2034
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2035
* complete this operation.
2036
* \end{itemize}
2037
*/
2038
2039
EXPORT_SPEC int UpnpSubscribe(
2040
IN UpnpClient_Handle Hnd, /** The handle of the control point. */
2041
IN const char *PublisherUrl, /** The URL of the service to subscribe to. */
2042
INOUT int *TimeOut, /** Pointer to a variable containing
2043
the requested subscription time. Upon
2044
return, it contains the actual
2045
subscription time returned from the
2046
service. */
2047
OUT Upnp_SID SubsId /** Pointer to a variable to receive the
2048
subscription ID (SID). */
2049
);
2050
2051
/** {\bf UpnpSubscribeAsync} performs the same operation as
2052
* {\bf UpnpSubscribe}, but returns immediately and calls the registered
2053
* callback function when the operation is complete.
2054
*
2055
* Note that many of the error codes for this function are returned in
2056
* the {\bf Upnp_Event_Subscribe} structure. In those cases, the function
2057
* returns {\tt UPNP_E_SUCCESS} and the appropriate error code will
2058
* be in the {\bf Upnp_Event_Subscribe.ErrCode} field in the {\bf Event}
2059
* structure passed to the callback.
2060
*
2061
* @return [int] An integer representing one of the following:
2062
* \begin{itemize}
2063
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2064
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
2065
* point handle.
2066
* \item {\tt UPNP_E_INVALID_URL}: The {\bf PublisherUrl} is not a valid
2067
* URL.
2068
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf TimeOut} or {\bf Fun} or
2069
* {\bf PublisherUrl} is not a valid pointer.
2070
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2071
* complete this operation.
2072
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured (returned in
2073
* the {\bf Upnp_Event_Subscribe.ErrCode} field as part of the
2074
* callback).
2075
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2076
* to a socket (returned in the
2077
* {\bf Upnp_Event_Subscribe.ErrCode} field as part of the
2078
* callback).
2079
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2080
* from a socket (returned in the
2081
* {\bf Upnp_Event_Subscribe.ErrCode} field as part of the
2082
* callback).
2083
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding the socket
2084
* (returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as
2085
* part of the callback).
2086
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to
2087
* {\bf PublisherUrl} (returned in the {\bf
2088
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
2089
* \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating the
2090
* socket (returned in the {\bf Upnp_Event_Subscribe.ErrCode}
2091
* field as part of the callback).
2092
* \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from
2093
* the publisher (returned in the {\bf
2094
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
2095
* \item {\tt UPNP_E_SUBSCRIBE_UNACCEPTED}: The publisher refused
2096
* the subscription request (returned in the {\bf
2097
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
2098
* \end{itemize}
2099
*/
2100
2101
EXPORT_SPEC int UpnpSubscribeAsync(
2102
IN UpnpClient_Handle Hnd, /** The handle of the control point that
2103
is subscribing. */
2104
IN const char *PublisherUrl, /** The URL of the service to subscribe
2105
to. */
2106
IN int TimeOut, /** The requested subscription time. Upon
2107
return, it contains the actual
2108
subscription time returned from the
2109
service. */
2110
IN Upnp_FunPtr Fun, /** Pointer to the callback function for
2111
this subscribe request. */
2112
IN const void *Cookie /** A user data value passed to the
2113
callback function when invoked. */
2114
);
2115
2116
/** {\bf UpnpUnSubscribe} removes the subscription of a control point from a
2117
* service previously subscribed to using {\bf UpnpSubscribe} or
2118
* {\bf UpnpSubscribeAsync}. This is a synchronous call.
2119
*
2120
* @return [int] An integer representing one of the following:
2121
* \begin{itemize}
2122
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2123
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
2124
* point handle.
2125
* \item {\tt UPNP_E_INVALID_SID}: The {\bf SubsId} is not a valid
2126
* subscription ID.
2127
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured.
2128
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2129
* to a socket.
2130
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2131
* from a socket.
2132
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
2133
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to
2134
* {\bf PublisherUrl}.
2135
* \item {\tt UPNP_E_OUTOF_SOCKET}: An error ocurred creating a socket.
2136
* \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from
2137
* the publisher.
2138
* \item {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED}: The publisher refused
2139
* the unsubscribe request (the client is still unsubscribed and
2140
* no longer receives events).
2141
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2142
* complete this operation.
2143
* \end{itemize}
2144
*/
2145
2146
EXPORT_SPEC int UpnpUnSubscribe(
2147
IN UpnpClient_Handle Hnd, /** The handle of the subscribed control
2148
point. */
2149
IN Upnp_SID SubsId /** The ID returned when the control point
2150
subscribed to the service. */
2151
);
2152
2153
/** {\bf UpnpUnSubscribeAsync} removes a subscription of a control
2154
* point from a service previously subscribed to using {\bf
2155
* UpnpSubscribe} or {\bf UpnpSubscribeAsync}, generating a callback
2156
* when the operation is complete.
2157
*
2158
* Note that many of the error codes for this function are returned in
2159
* the {\bf Upnp_Event_Subscribe} structure. In those cases, the function
2160
* returns {\tt UPNP_E_SUCCESS} and the appropriate error code will
2161
* be in the {\bf Upnp_Event_Subscribe.ErrCode} field in the {\bf Event}
2162
* structure passed to the callback.
2163
*
2164
* @return [int] An integer representing one of the following:
2165
* \begin{itemize}
2166
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2167
* \item {\tt UPNP_E_INVALID_HANDLE}: The handle is not a valid control
2168
* point handle.
2169
* \item {\tt UPNP_E_INVALID_SID}: The {\bf SubsId} is not a valid SID.
2170
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf Fun} is not a valid callback
2171
* function pointer.
2172
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2173
* complete this operation.
2174
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occured (returned in
2175
* the {\bf Upnp_Event_Subscribe.ErrCode} field as part of the
2176
* callback).
2177
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2178
* to a socket (returned in the {\bf
2179
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
2180
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2181
* from a socket (returned in the
2182
* {\bf Upnp_Event_Subscribe.ErrCode} field as part of the
2183
* callback).
2184
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding the socket
2185
* (returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as
2186
* part of the callback).
2187
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting to
2188
* {\bf PublisherUrl} (returned in the {\bf
2189
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
2190
* \item {\tt UPNP_E_OUTOF_SOCKET}: An error occurred creating a socket (
2191
* returned in the {\bf Upnp_Event_Subscribe.ErrCode} field as
2192
* part of the callback).
2193
* \item {\tt UPNP_E_BAD_RESPONSE}: An error occurred in response from
2194
* the publisher (returned in the {\bf
2195
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
2196
* \item {\tt UPNP_E_UNSUBSCRIBE_UNACCEPTED}: The publisher refused
2197
* the subscription request (returned in the {\bf
2198
* Upnp_Event_Subscribe.ErrCode} field as part of the callback).
2199
* \end{itemize} */
2200
2201
EXPORT_SPEC int UpnpUnSubscribeAsync(
2202
IN UpnpClient_Handle Hnd, /** The handle of the subscribed control
2203
point. */
2204
IN Upnp_SID SubsId, /** The ID returned when the
2205
control point subscribed to the service. */
2206
IN Upnp_FunPtr Fun, /** Pointer to a callback function to be
2207
called when the operation is complete. */
2208
IN const void *Cookie /** Pointer to user data to pass to the
2209
callback function when invoked. */
2210
);
2211
2212
//@} // Eventing
2213
2214
2215
////////////////////////////////////////////////////////////////////////
2216
////////////////////////////////////////////////////////////////////////
2217
// //
2218
// C L I E N T - A P I //
2219
// //
2220
////////////////////////////////////////////////////////////////////////
2221
////////////////////////////////////////////////////////////////////////
2222
2223
///@name Control Point HTTP API
2224
//@{
2225
2226
/** {\bf UpnpDownloadUrlItem} downloads a file specified in a URL.
2227
* The SDK allocates the memory for {\bf outBuf} and the
2228
* application is responsible for freeing this memory. Note that
2229
* the item is passed as a single buffer. Large items should not
2230
* be transferred using this function.
2231
*
2232
* @return [int] An integer representing one of the following:
2233
* \begin{itemize}
2234
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2235
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf outBuf}
2236
* or {\bf contentType} is not a valid pointer.
2237
* \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid
2238
* URL.
2239
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2240
* download this file.
2241
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred.
2242
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2243
* to a socket.
2244
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2245
* from a socket.
2246
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
2247
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a
2248
* socket.
2249
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
2250
* allocated.
2251
* \end{itemize}
2252
*/
2253
2254
EXPORT_SPEC int UpnpDownloadUrlItem(
2255
IN const char *url, /** URL of an item to download. */
2256
OUT char **outBuf, /** Buffer to store the downloaded item. */
2257
OUT char *contentType /** HTTP header value content type if
2258
present. It should be at least
2259
{\tt LINE_SIZE} bytes in size. */
2260
);
2261
2262
/** {\bf UpnpOpenHttpGet} gets a file specified in a URL.
2263
* The SDK allocates the memory for {\bf handle} and
2264
* {\bf contentType}, the application is responsible for freeing this memory.
2265
*
2266
* @return [int] An integer representing one of the following:
2267
* \begin{itemize}
2268
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2269
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf handle},
2270
* {\bf contentType}, {\bf contentLength} or {\bf httpStatus}
2271
* is not a valid pointer.
2272
* \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid
2273
* URL.
2274
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2275
* download this file.
2276
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred.
2277
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2278
* to a socket.
2279
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2280
* from a socket.
2281
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
2282
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a
2283
* socket.
2284
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
2285
* allocated.
2286
* \item {\tt UPNP_E_BAD_RESPONSE}: A bad response was received from the
2287
* remote server.
2288
* \end{itemize}
2289
*/
2290
2291
EXPORT_SPEC int UpnpOpenHttpGet(
2292
IN const char *url, /** The URL of an item to get. */
2293
IN OUT void **handle, /** A pointer to store the handle for
2294
this connection. */
2295
IN OUT char **contentType, /** A buffer to store the media type of
2296
the item. */
2297
IN OUT off_t *contentLength, /** A pointer to store the length of the
2298
item. */
2299
IN OUT int *httpStatus, /** The status returned on receiving a
2300
response message. */
2301
IN int timeout /** The time out value sent with the
2302
request during which a response is
2303
expected from the server, failing
2304
which, an error is reported back to
2305
the user. */
2306
);
2307
2308
/** {\bf UpnpOpenHttpGetProxy} gets a file specified in a URL through the
2309
* specified proxy.
2310
* The SDK allocates the memory for {\bf handle} and
2311
* {\bf contentType}, the application is responsible for freeing this memory.
2312
*
2313
* @return [int] An integer representing one of the following:
2314
* \begin{itemize}
2315
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2316
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf handle},
2317
* {\bf contentType}, {\bf contentLength} or {\bf httpStatus}
2318
* is not a valid pointer.
2319
* \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid
2320
* URL.
2321
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2322
* download this file.
2323
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred.
2324
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2325
* to a socket.
2326
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2327
* from a socket.
2328
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
2329
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a
2330
* socket.
2331
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
2332
* allocated.
2333
* \item {\tt UPNP_E_BAD_RESPONSE}: A bad response was received from the
2334
* remote server.
2335
* \end{itemize}
2336
*/
2337
2338
EXPORT_SPEC int UpnpOpenHttpGetProxy(
2339
IN const char *url, /** The URL of an item to get. */
2340
IN const char *proxy_str, /** The URL of the proxy. */
2341
IN OUT void **handle, /** A pointer to store the handle for
2342
this connection. */
2343
IN OUT char **contentType, /** A buffer to store the media type of
2344
the item. */
2345
IN OUT off_t *contentLength, /** A pointer to store the length of the
2346
item. */
2347
IN OUT int *httpStatus, /** The status returned on receiving a
2348
response message. */
2349
IN int timeout /** The time out value sent with the
2350
request during which a response is
2351
expected from the server, failing
2352
which, an error is reported back to
2353
the user. */
2354
);
2355
2356
/** {\bf UpnpOpenHttpGetEx} gets specified number of bytes from a file
2357
* specified in the URL. The number of bytes is specified through a low
2358
* count and a high count which are passed as a range of bytes for the
2359
* request. The SDK allocates the memory for {\bf handle} and
2360
* {\bf contentType}, the application is responsible for freeing this memory.
2361
*
2362
* @return [int] An integer representing one of the following:
2363
* \begin{itemize}
2364
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2365
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf handle},
2366
* {\bf contentType}, {\bf contentLength} or {\bf httpStatus}
2367
* is not a valid pointer.
2368
* \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid
2369
* URL.
2370
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2371
* download this file.
2372
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred.
2373
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2374
* to a socket.
2375
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2376
* from a socket.
2377
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
2378
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a
2379
* socket.
2380
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
2381
* allocated.
2382
* \item {\tt UPNP_E_BAD_RESPONSE}: A bad response was received from the
2383
* remote server.
2384
* \end{itemize}
2385
*/
2386
2387
EXPORT_SPEC int UpnpOpenHttpGetEx(
2388
IN const char *url, /** The URL of the item to get. */
2389
IN OUT void **handle, /** A pointer to store the handle for
2390
this connection. */
2391
IN OUT char **contentType, /** A buffer to store the media type of the
2392
item. */
2393
IN OUT off_t *contentLength, /** A buffer to store the length of the
2394
item. */
2395
IN OUT int *httpStatus, /** The status returned on receiving a
2396
response message from the remote
2397
server. */
2398
IN int lowRange, /** An integer value representing the low
2399
end of a range to retrieve. */
2400
IN int highRange, /** An integer value representing the high
2401
end of a range to retrieve. */
2402
IN int timeout /** A time out value sent with the request
2403
during which a response is expected
2404
from the server, failing which, an
2405
error is reported back to the user. */
2406
);
2407
2408
/** {\bf UpnpReadHttpGet} gets specified number of bytes from a file
2409
* specified in a URL.
2410
*
2411
* @return [int] An integer representing one of the following:
2412
* \begin{itemize}
2413
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2414
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf handle}, {\bf buf}
2415
* or {\bf size} is not a valid pointer.
2416
* \item {\tt UPNP_E_BAD_RESPONSE}: A bad response was received from the
2417
* remote server.
2418
* \item {\tt UPNP_E_BAD_HTTPMSG}: Either the request or response was in
2419
* the incorrect format.
2420
* \item {\tt UPNP_E_CANCELED}: another thread called UpnpCancelHttpGet.
2421
* \end{itemize}
2422
*
2423
* Note: In case of return values, the status code parameter of the passed
2424
* in handle value may provide additional information on the return
2425
* value.
2426
*/
2427
2428
EXPORT_SPEC int UpnpReadHttpGet(
2429
IN void *handle, /** The token created by the call to
2430
{\bf UpnpOpenHttpGet}. */
2431
IN OUT char *buf, /** The buffer to store the read item. */
2432
IN OUT off_t *size, /** The size of the buffer to be read. */
2433
IN int timeout /** The time out value sent with the
2434
request during which a response is
2435
expected from the server, failing
2436
which, an error is reported back to
2437
the user. */
2438
);
2439
2440
/** {\bf UpnpHttpGetProgress} rettrieve progress information of a http-get
2441
* transfer.
2442
*
2443
* @return [int] An integer representing one of the following:
2444
* \begin{itemize}
2445
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2446
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf handle}, {\bf length}
2447
* or {\bf total} is not a valid pointer.
2448
* \end{itemize}
2449
*
2450
*/
2451
EXPORT_SPEC int UpnpHttpGetProgress(
2452
IN void *handle, /** The token created by the call to
2453
{\bf UpnpOpenHttpGet}. */
2454
OUT off_t *length, /** The number of bytes received. */
2455
OUT off_t *total /** The content length. */
2456
);
2457
2458
2459
/** {\bf UpnpCancelHttpGet} set the cancel flag of the {\bf handle}
2460
* parameter.
2461
*
2462
* @return [int] An integer representing one of the following:
2463
* \begin{itemize}
2464
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2465
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf handle} is not a valid pointer.
2466
* \end{itemize}
2467
*/
2468
2469
EXPORT_SPEC int UpnpCancelHttpGet(IN void *handle);
2470
2471
/** {\bf UpnpCloseHttpGet} closes the connection and frees memory that was
2472
* allocated for the {\bf handle} parameter.
2473
*
2474
* @return [int] An integer representing one of the following:
2475
* \begin{itemize}
2476
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2477
* \item {\tt UPNP_E_INVALID_PARAM}: {\bf handle} is not a valid pointer.
2478
* \end{itemize}
2479
*/
2480
2481
EXPORT_SPEC int UpnpCloseHttpGet(IN void *handle);
2482
2483
2484
/** {\bf UpnpOpenHttpPost} makes an HTTP POST request message, opens a
2485
* connection to the server and sends the POST request to the server if
2486
* the connection to the server succeeds.
2487
* The SDK allocates the memory for {\bf handle} and
2488
* {\bf contentType}, the application is responsible for freeing this memory.
2489
*
2490
* @return [int] An integer representing one of the following:
2491
* \begin{itemize}
2492
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2493
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url}, {\bf handle}
2494
* or {\bf contentType} is not a valid pointer.
2495
* \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid
2496
* URL.
2497
* \item {\tt UPNP_E_OUTOF_MEMORY}: Insufficient resources exist to
2498
* download this file.
2499
* \item {\tt UPNP_E_SOCKET_ERROR}: Error occured allocating a socket and
2500
* resources or an error occurred binding a socket.
2501
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2502
* to a socket.
2503
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting a
2504
* socket.
2505
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
2506
* allocated.
2507
* \end{itemize}
2508
*/
2509
2510
EXPORT_SPEC int UpnpOpenHttpPost(
2511
IN const char *url, /** The URL in which to send the POST
2512
request. */
2513
IN OUT void **handle, /** A pointer in which to store the
2514
handle for this connection. This
2515
handle is required for futher
2516
operations over this connection. */
2517
IN const char *contentType, /** A buffer to store the media type of
2518
content being sent. */
2519
IN int contentLength, /** The length of the content, in bytes,
2520
being posted. */
2521
IN int timeout /** The time out value sent with the
2522
request during which a response is
2523
expected from the receiver, failing
2524
which, an error is reported. */
2525
);
2526
2527
2528
/** {\bf UpnpWriteHttpPost} sends a request to a server to copy the contents of
2529
* a buffer to the URI specified in the {\bf UpnpOpenHttpPost} call.
2530
*
2531
* @return [int] An integer representing one of the following:
2532
* \begin{itemize}
2533
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2534
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf handle}, {\bf buf}
2535
* or {\bf size} is not a valid pointer.
2536
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2537
* to a socket.
2538
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
2539
* allocated.
2540
* \end{itemize}
2541
*/
2542
2543
EXPORT_SPEC int UpnpWriteHttpPost(
2544
IN void *handle, /** The handle of the connection created
2545
by the call to {\bf UpnpOpenHttpPost}. */
2546
IN char *buf, /** The buffer to be posted. */
2547
IN off_t *size, /** The size, in bytes of {\bf buf}. */
2548
IN int timeout /** A timeout value sent with the request
2549
during which a response is expected
2550
from the server, failing which, an
2551
error is reported. */
2552
);
2553
2554
/** {\bf UpnpCloseHttpPost} sends and receives any pending data, closes the
2555
* connection with the server, and frees memory allocated during the
2556
* {\bfUpnpOpenHttpPost} call.
2557
*
2558
* @return [int] An integer representing one of the following:
2559
* \begin{itemize}
2560
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2561
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf handle}, or
2562
* {\bf httpStatus} is not a valid pointer.
2563
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2564
* from a socket.
2565
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
2566
* allocated.
2567
* \end{itemize}
2568
*/
2569
2570
EXPORT_SPEC int UpnpCloseHttpPost(
2571
IN void *handle, /** The handle of the connection to close,
2572
created by the call to
2573
{\bf UpnpOpenHttpPost}. */
2574
IN OUT int *httpStatus, /** A pointer to a buffer to store the
2575
final status of the connection. */
2576
IN int timeout /** A time out value sent with the request
2577
during which a response is expected from
2578
the server, failing which, an error is
2579
reported. */
2580
);
2581
2582
2583
/** {\bf UpnpDownloadXmlDoc} downloads an XML document specified in a URL.
2584
* The SDK parses the document and returns it in the form of a
2585
* DOM document. The application is responsible for freeing the DOM document.
2586
*
2587
* @return [int] An integer representing one of the following:
2588
* \begin{itemize}
2589
* \item {\tt UPNP_E_SUCCESS}: The operation completed successfully.
2590
* \item {\tt UPNP_E_INVALID_PARAM}: Either {\bf url} or {\bf xmlDoc}
2591
* is not a valid pointer.
2592
* \item {\tt UPNP_E_INVALID_DESC}: The XML document was not
2593
* found or it does not contain a valid XML description.
2594
* \item {\tt UPNP_E_INVALID_URL}: The {\bf url} is not a valid
2595
* URL.
2596
* \item {\tt UPNP_E_OUTOF_MEMORY}: There are insufficient resources to
2597
* download the XML document.
2598
* \item {\tt UPNP_E_NETWORK_ERROR}: A network error occurred.
2599
* \item {\tt UPNP_E_SOCKET_WRITE}: An error or timeout occurred writing
2600
* to a socket.
2601
* \item {\tt UPNP_E_SOCKET_READ}: An error or timeout occurred reading
2602
* from a socket.
2603
* \item {\tt UPNP_E_SOCKET_BIND}: An error occurred binding a socket.
2604
* \item {\tt UPNP_E_SOCKET_CONNECT}: An error occurred connecting the
2605
* socket.
2606
* \item {\tt UPNP_E_OUTOF_SOCKET}: Too many sockets are currently
2607
* allocated.
2608
* \end{itemize}
2609
*/
2610
2611
EXPORT_SPEC int UpnpDownloadXmlDoc(
2612
IN const char *url, /** URL of the XML document. */
2613
OUT IXML_Document **xmlDoc /** A pointer in which to store the
2614
XML document. */
2615
);
2616
2617
//@} // Control Point HTTP API
2618
2619
////////////////////////////////////////////////////////////////////////
2620
////////////////////////////////////////////////////////////////////////
2621
// //
2622
// W E B S E R V E R A P I //
2623
// //
2624
////////////////////////////////////////////////////////////////////////
2625
////////////////////////////////////////////////////////////////////////
2626
2627
///@name Web Server API
2628
//@{
2629
2630
/** {\bf UpnpSetWebServerRootDir} sets the document root directory for
2631
* the internal web server. This directory is considered the
2632
* root directory (i.e. "/") of the web server.
2633
*
2634
* This function also activates or deactivates the web server.
2635
* To disable the web server, pass {\tt NULL} for {\bf rootDir}; to
2636
* activate, pass a valid directory string.
2637
*
2638
* Note that this function is not available when the web server is not
2639
* compiled into the SDK.
2640
*
2641
* @return [int] An integer representing one of the following:
2642
* \begin{itemize}
2643
* \item {\tt UPPN_E_SUCCESS}: The operation completed successfully.
2644
* \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf rootDir} is an invalid
2645
* directory.
2646
* \end{itemize}
2647
*/
2648
2649
EXPORT_SPEC int UpnpSetWebServerRootDir(
2650
IN const char* rootDir /** Path of the root directory of the web
2651
server. */
2652
);
2653
2654
/** {\bf UpnpAddHTTPHeader} add a custom header to
2655
* the internal web server. All HTTP responses will contain the
2656
* specified header.
2657
*
2658
* @return [int] An integer representing one of the following:
2659
* \begin{itemize}
2660
* \item {\tt UPPN_E_SUCCESS}: The operation completed successfully.
2661
* \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf header_string} is empty.
2662
* \end{itemize}
2663
*/
2664
2665
EXPORT_SPEC int UpnpAddCustomHTTPHeader(
2666
IN const char* header_string /** Header to add (\r\n termination not needed) */
2667
);
2668
2669
/** {\bf UpnpRemoveHTTPHeader} removes a header that was previously added
2670
* with {\bf UpnpAddHTTPHeader}.
2671
*
2672
* @return [int] An integer representing one of the following:
2673
* \begin{itemize}
2674
* \item {\tt UPPN_E_SUCCESS}: The operation completed successfully.
2675
* \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf dirName} is not valid.
2676
* \end{itemize}
2677
*/
2678
2679
EXPORT_SPEC int UpnpRemoveCustomHTTPHeader(
2680
IN const char* header_string /** Name of the header to remove */
2681
);
2682
2683
/** {\bf UpnpRemoveAll} removes all virtual directory mappings.
2684
*
2685
* @return [void] This function does not return a value.
2686
*
2687
*/
2688
2689
EXPORT_SPEC void UpnpRemoveAllCustomHTTPHeaders( );
2690
2691
2692
/** {\bf UpnpSetVirtualDirCallbacks} sets the callback function to be used to
2693
* access a virtual directory. Refer to the description of
2694
* {\bf UpnpVirtualDirCallbacks} for a description of the functions.
2695
*
2696
* @return [int] An integer representing one of the following:
2697
* \begin{itemize}
2698
* \item {\tt UPPN_E_SUCCESS}: The operation completed successfully.
2699
* \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf callbacks} is not a valid
2700
* pointer.
2701
* \end{itemize}
2702
*/
2703
2704
EXPORT_SPEC int UpnpSetVirtualDirCallbacks(
2705
IN struct UpnpVirtualDirCallbacks *callbacks /** Pointer to a structure
2706
containing points to the
2707
virtual interface
2708
functions. */
2709
);
2710
2711
/** {\bf UpnpEnableWebServer} enables or disables the webserver. A value of
2712
* {\tt TRUE} enables the webserver, {\tt FALSE} disables it.
2713
*
2714
* @return [int] An integer representing one of the following:
2715
* \begin{itemize}
2716
* \item {\tt UPPN_E_SUCCESS}: The operation completed successfully.
2717
* \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf enable} is not valid.
2718
* \end{itemize}
2719
*/
2720
2721
EXPORT_SPEC int UpnpEnableWebserver(
2722
IN int enable /** {\tt TRUE} to enable, {\tt FALSE} to disable. */
2723
);
2724
2725
/** {\bf UpnpIsWebServerEnabled} returns {\tt TRUE} if the webserver is
2726
* enabled, or {\tt FALSE} if it is not.
2727
*
2728
* @return [int] An integer representing one of the following:
2729
* \begin{itemize}
2730
* \item {\tt TRUE}: The webserver is enabled.
2731
* \item {\tt FALSE}: The webserver is not enabled
2732
* \end{itemize}
2733
*/
2734
2735
EXPORT_SPEC int UpnpIsWebserverEnabled();
2736
2737
/** {\bf UpnpAddVirtualDir} adds a virtual directory mapping.
2738
*
2739
* All webserver requests containing the given directory are read using
2740
* functions contained in a {\bf UpnpVirtualDirCallbacks} structure registered
2741
* via {\bf UpnpSetVirtualDirCallbacks}.
2742
*
2743
* @return [int] An integer representing one of the following:
2744
* \begin{itemize}
2745
* \item {\tt UPPN_E_SUCCESS}: The operation completed successfully.
2746
* \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf dirName} is not valid.
2747
* \end{itemize}
2748
*/
2749
2750
EXPORT_SPEC int UpnpAddVirtualDir(
2751
IN const char *dirName /** The name of the new directory mapping to add.
2752
*/
2753
);
2754
2755
/** {\bf UpnpRemoveVirtualDir} removes a virtual directory mapping made with
2756
* {\bf UpnpAddVirtualDir}.
2757
*
2758
* @return [int] An integer representing one of the following:
2759
* \begin{itemize}
2760
* \item {\tt UPPN_E_SUCCESS}: The operation completed successfully.
2761
* \item {\tt UPNP_E_INVALID_ARGUMENT}: {\bf dirName} is not valid.
2762
* \end{itemize}
2763
*/
2764
2765
EXPORT_SPEC int UpnpRemoveVirtualDir(
2766
IN const char *dirName /** The name of the virtual directory mapping to
2767
remove. */
2768
);
2769
2770
/** {\bf UpnpRemoveAllVirtualDirs} removes all virtual directory mappings.
2771
*
2772
* @return [void] This function does not return a value.
2773
*
2774
*/
2775
2776
EXPORT_SPEC void UpnpRemoveAllVirtualDirs( );
2777
2778
EXPORT_SPEC void UpnpFree(
2779
IN void *item /* The item to free. */
2780
);
2781
2782
//@} // Web Server API
2783
2784
#ifdef __cplusplus
2785
}
2786
#endif // __cplusplus
2787
2788
//@} The API
2789
2790
#endif
2791
Loggerhead is a web-based interface for Breezy
Version: 2.0.1