src/extern/upnp/upnp.h

   1 ///////////////////////////////////////////////////////////////////////////
   2 //
   3 // Copyright (c) 2000-2003 Intel Corporation
   4 // All rights reserved.
   5 //
   6 // Redistribution and use in source and binary forms, with or without
   7 // modification, are permitted provided that the following conditions are met:
   8 //
   9 // * Redistributions of source code must retain the above copyright notice,
  10 // this list of conditions and the following disclaimer.
  11 // * Redistributions in binary form must reproduce the above copyright notice,
  12 // this list of conditions and the following disclaimer in the documentation
  13 // and/or other materials provided with the distribution.
  14 // * Neither name of Intel Corporation nor the names of its contributors
  15 // may be used to endorse or promote products derived from this software
  16 // without specific prior written permission.
  17 //
  18 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL OR
  22 // CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  23 // EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  24 // PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  25 // PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
  26 // OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  27 // NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28 // SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 //
  30 ///////////////////////////////////////////////////////////////////////////
  31
  32 // Modified by Angel Vidal Veiga (kry@amule.org) for the aMule project.
  33 // Really crippled version of the original header. Keep just what we need.
  34
  35 #ifndef UPNP_H
  36 #define UPNP_H
  37
  38 #include "ixml.h"
  39
  40 #ifndef __WIN32__
  41 #include <sys/types.h>
  42 #include <netinet/in.h>
  43 #else
  44 #include <winsock.h>
  45 #endif
  46
  47 #define LINE_SIZE  180
  48 #define NAME_SIZE  256
  49
  50 /// @name Constants, Structures, and Types
  51 //@{
  52
  53 /** @name UPNP_E_SUCCESS [0]
  54  *  {\tt UPNP_E_SUCCESS} signifies that the operation completed successfully.
  55  *  For asynchronous functions, this only means that the packet generated by
  56  *  the operation was successfully transmitted on the network.  The result of
  57  *  the entire operation comes as part of the callback for that operation.
  58  */
  59 //@{
  60 #define UPNP_E_SUCCESS          0
  61 //@}
  62
  63 /** Returned when a control point application registers with {\bf
  64  *  UpnpRegisterClient}.  Client handles can only be used with
  65  *  functions that operate with a client handle.  */
  66
  67 typedef int  UpnpClient_Handle;
  68
  69 /** @name UPnP_EventType
  70     @memo The reason code for an event callback.
  71     @doc The {\bf Event} parameter will be different depending on the
  72          reason for the callback.  The descriptions for each event
  73          type describe the contents of the {\bf Event} parameter.
  74   */
  75
  76 enum Upnp_EventType_e {
  77
  78   //
  79   // Control callbacks
  80   //
  81
  82   /** Received by a device when a control point issues a control
  83    *  request.  The {\bf Event} parameter contains a pointer to a {\bf
  84    *  Upnp_Action_Request} structure containing the action.  The application
  85    *  stores the results of the action in this structure. */
  86
  87   UPNP_CONTROL_ACTION_REQUEST,
  88
  89   /** A {\bf UpnpSendActionAsync} call completed. The {\bf Event}
  90    *  parameter contains a pointer to a {\bf Upnp_Action_Complete} structure
  91    *  with the results of the action.  */
  92
  93   UPNP_CONTROL_ACTION_COMPLETE,
  94
  95   /** Received by a device when a query for a single service variable
  96    *  arrives.  The {\bf Event} parameter contains a pointer to a {\bf
  97    *  Upnp_State_Var_Request} structure containing the name of the variable
  98    *  and value.  */
  99
 100   UPNP_CONTROL_GET_VAR_REQUEST,
 101
 102   /** A {\bf UpnpGetServiceVarStatus} call completed. The {\bf Event}
 103    *  parameter contains a pointer to a {\bf Upnp_State_Var_Complete} structure
 104    *  containing the value for the variable.  */
 105
 106   UPNP_CONTROL_GET_VAR_COMPLETE,
 107
 108   //
 109   // Discovery callbacks
 110   //
 111
 112   /** Received by a control point when a new device or service is available.
 113    *  The {\bf Event} parameter contains a pointer to a {\bf
 114    *  Upnp_Discovery} structure with the information about the device
 115    *  or service.  */
 116
 117   UPNP_DISCOVERY_ADVERTISEMENT_ALIVE,
 118
 119   /** Received by a control point when a device or service shuts down. The {\bf
 120    *  Event} parameter contains a pointer to a {\bf Upnp_Discovery}
 121    *  structure containing the information about the device or
 122    *  service.  */
 123
 124   UPNP_DISCOVERY_ADVERTISEMENT_BYEBYE,
 125
 126   /** Received by a control point when a matching device or service responds.
 127    *  The {\bf Event} parameter contains a pointer to a {\bf
 128    *  Upnp_Discovery} structure containing the information about
 129    *  the reply to the search request.  */
 130
 131   UPNP_DISCOVERY_SEARCH_RESULT,
 132
 133   /** Received by a control point when the search timeout expires.  The
 134    *  SDK generates no more callbacks for this search after this
 135    *  event.  The {\bf Event} parameter is {\tt NULL}.  */
 136
 137   UPNP_DISCOVERY_SEARCH_TIMEOUT,
 138
 139   //
 140   // Eventing callbacks
 141   //
 142
 143   /** Received by a device when a subscription arrives.
 144    *  The {\bf Event} parameter contains a pointer to a {\bf
 145    *  Upnp_Subscription_Request} structure.  At this point, the
 146    *  subscription has already been accepted.  {\bf UpnpAcceptSubscription}
 147    *  needs to be called to confirm the subscription and transmit the
 148    *  initial state table.  This can be done during this callback.  The SDK
 149    *  generates no events for a subscription unless the device
 150    *  application calls {\bf UpnpAcceptSubscription}.
 151    */
 152
 153   UPNP_EVENT_SUBSCRIPTION_REQUEST,
 154
 155   /** Received by a control point when an event arrives.  The {\bf
 156    *  Event} parameter contains a {\bf Upnp_Event} structure
 157    *  with the information about the event.  */
 158
 159   UPNP_EVENT_RECEIVED,
 160
 161   /** A {\bf UpnpRenewSubscriptionAsync} call completed. The status of
 162    *  the renewal is in the {\bf Event} parameter as a {\bf
 163    *  Upnp_Event_Subscription} structure.  */
 164
 165   UPNP_EVENT_RENEWAL_COMPLETE,
 166
 167   /** A {\bf UpnpSubscribeAsync} call completed. The status of the
 168    * subscription is in the {\bf Event} parameter as a {\bf
 169    * Upnp_Event_Subscription} structure.  */
 170
 171   UPNP_EVENT_SUBSCRIBE_COMPLETE,
 172
 173   /** A {\bf UpnpUnSubscribeAsync} call completed. The status of the
 174    *  subscription is in the {\bf Event} parameter as a {\bf
 175    *  Upnp_Event_Subscribe} structure.  */
 176
 177   UPNP_EVENT_UNSUBSCRIBE_COMPLETE,
 178
 179   /** The auto-renewal of a client subscription failed.
 180    *  The {\bf Event} parameter is a {\bf Upnp_Event_Subscribe} structure
 181    *  with the error code set appropriately. The subscription is no longer
 182    *  valid. */
 183
 184   UPNP_EVENT_AUTORENEWAL_FAILED,
 185
 186   /** A client subscription has expired. This will only occur
 187    *  if auto-renewal of subscriptions is disabled.
 188    *  The {\bf Event} parameter is a {\bf Upnp_Event_Subscribe}
 189    *  structure. The subscription is no longer valid. */
 190
 191   UPNP_EVENT_SUBSCRIPTION_EXPIRED
 192
 193 };
 194
 195 typedef enum Upnp_EventType_e Upnp_EventType;
 196
 197 /** The {\bf Upnp_SID} holds the subscription identifier for a subscription
 198     between a client and a device.  The SID is a string representation of
 199     a globally unique id (GUID) and should not be modified.
 200   */
 201
 202 typedef char Upnp_SID[44];
 203
 204 /** All callback functions share the same prototype, documented below.
 205  *  Note that any memory passed to the callback function
 206  *  is valid only during the callback and should be copied if it
 207  *  needs to persist.  This callback function needs to be thread
 208  *  safe.  The context of the callback is always on a valid thread
 209  *  context and standard synchronization methods can be used.  Note,
 210  *  however, because of this the callback cannot call SDK functions
 211  *  unless explicitly noted.
 212  *
 213  *  \begin{verbatim}
 214       int CallbackFxn( Upnp_EventType EventType, void* Event, void* Cookie );
 215     \end{verbatim}
 216  *
 217  *  where {\bf EventType} is the event that triggered the callback,
 218  *  {\bf Event} is a structure that denotes event-specific information for that
 219  *  event, and {\bf Cookie} is the user data passed when the callback was
 220  *  registered.
 221  *
 222  *  See {\bf Upnp_EventType} for more information on the callback values and
 223  *  the associated {\bf Event} parameter.
 224  *
 225  *  The return value of the callback is currently ignored.  It may be used
 226  *  in the future to communicate results back to the SDK.
 227  */
 228
 229 typedef int  (*Upnp_FunPtr) (
 230     IN Upnp_EventType EventType,
 231     IN void *Event,
 232     IN void *Cookie
 233     );
 234
 235 //
 236 // This typedef is required by Doc++ to parse the last entry of the
 237 // Upnp_Discovery structure correctly.
 238 //
 239
 240 struct Upnp_Discovery
 241 {
 242         /** The result code of the {\bf UpnpSearchAsync} call. */
 243         int  ErrCode;
 244
 245         /** The expiration time of the advertisement. */
 246         int  Expires;
 247
 248         /** The unique device identifier. */
 249         char DeviceId[LINE_SIZE];
 250
 251         /** The device type. */
 252         char DeviceType[LINE_SIZE];
 253
 254         /** The service type. */
 255         char ServiceType[LINE_SIZE];
 256
 257         /** The service version. */
 258         char ServiceVer[LINE_SIZE];
 259
 260         /** The URL to the UPnP description document for the device. */
 261         char Location[LINE_SIZE];
 262
 263         /** The operating system the device is running. */
 264         char Os[LINE_SIZE];
 265
 266         /** Date when the response was generated. */
 267         char Date[LINE_SIZE];
 268
 269         /** Confirmation that the MAN header was understood by the device. */
 270         char Ext[LINE_SIZE];
 271
 272         /** The host address of the device responding to the search. */
 273         struct sockaddr_in DestAddr;
 274 };
 275
 276 struct Upnp_Action_Complete
 277 {
 278   /** The result of the operation. */
 279   int ErrCode;
 280
 281   /** The control URL for service. */
 282   char CtrlUrl[NAME_SIZE];
 283
 284   /** The DOM document describing the action. */
 285   IXML_Document *ActionRequest;
 286
 287   /** The DOM document describing the result of the action. */
 288   IXML_Document *ActionResult;
 289 };
 290
 291 /** Represents the reply for the current value of a state variable in an
 292     asynchronous call. */
 293
 294 struct Upnp_State_Var_Complete
 295 {
 296   /** The result of the operation. */
 297   int ErrCode;
 298
 299   /** The control URL for the service. */
 300   char CtrlUrl[NAME_SIZE];
 301
 302   /** The name of the variable. */
 303   char StateVarName[NAME_SIZE];
 304
 305   /** The current value of the variable or error string in case of error. */
 306   DOMString CurrentVal;
 307 };
 308
 309 /** Returned along with a {\bf UPNP_EVENT_RECEIVED} callback.  */
 310
 311 struct Upnp_Event
 312 {
 313   /** The subscription ID for this subscription. */
 314   Upnp_SID Sid;
 315
 316   /** The event sequence number. */
 317   int EventKey;
 318
 319   /** The DOM tree representing the changes generating the event. */
 320   IXML_Document *ChangedVariables;
 321
 322 };
 323
 324 /** Returned along with a {\bf UPNP_EVENT_SUBSCRIBE_COMPLETE} or {\bf
 325  * UPNP_EVENT_UNSUBSCRIBE_COMPLETE} callback.  */
 326
 327 struct Upnp_Event_Subscribe {
 328
 329   /** The SID for this subscription.  For subscriptions, this only
 330    *  contains a valid SID if the {\bf Upnp_EventSubscribe.result} field
 331    *  contains a {\tt UPNP_E_SUCCESS} result code.  For unsubscriptions,
 332    *  this contains the SID from which the subscription is being
 333    *  unsubscribed.  */
 334
 335   Upnp_SID Sid;
 336
 337   /** The result of the operation. */
 338   int ErrCode;
 339
 340   /** The event URL being subscribed to or removed from. */
 341   char PublisherUrl[NAME_SIZE];
 342
 343   /** The actual subscription time (for subscriptions only). */
 344   int TimeOut;
 345
 346 };
 347
 348 //@} // Constants, Structures, and Types
 349
 350 #endif
 351
 352 // File_checked_for_headers