UPnP_Programming_Guide

Linux SDK for UPnP Devices v1.4 Contents 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3 About Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 4 The API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.1 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.1.1 UPNP E SUCCESS [0] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.1.2 UPNP E INVALID HANDLE [-100] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 4.1.3 UPNP E INVALID PARAM [-101] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1.4 UPNP E OUTOF HANDLE [-102] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1.5 UPNP E OUTOF MEMORY [-104] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1.6 UPNP E INIT [-105] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1.7 UPNP E INVALID DESC [-107] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.1.8 UPNP E INVALID URL [-108] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.9 UPNP E INVALID SERVICE [-111] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.10 UPNP E BAD RESPONSE [-113] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.11 UPNP E INVALID ACTION [-115] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.12 UPNP E FINISH [-116] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.1.13 UPNP E INIT FAILED [-117] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1.14 UPNP E BAD HTTPMSG [-119] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1.15 UPNP E ALREADY REGISTERED [-120] . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1.16 UPNP E NETWORK ERROR [-200] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1.17 UPNP E SOCKET WRITE [-201] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 4.1.18 UPNP E SOCKET READ [-202] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1.19 UPNP E SOCKET BIND [-203] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1.20 UPNP E SOCKET CONNECT [-204] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1.21 UPNP E OUTOF SOCKET [-205] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1.22 UPNP E LISTEN [-206] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4.1.23 UPNP E TIMEDOUT [-207] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.1.24 UPNP E SOCKET ERROR [-208] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.1.25 UPNP E CANCELED [-210] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.1.26 UPNP E SUBSCRIBE UNACCEPTED [-301] . . . . . . . . . . . . . . . . . . . . . . 14 4.1.27 UPNP E UNSUBSCRIBE UNACCAPTED [-302] . . . . . . . . . . . . . . . . . . 14 4.1.28 UPNP E NOTIFY UNACCEPTED [-303] . . . . . . . . . . . . . . . . . . . . . . . . . . 14 4.1.29 UPNP E INVALID ARGUMENT [-501] . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.1.30 UPNP E FILE NOT FOUND [-502] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.1.31 UPNP E FILE READ ERROR [-503] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.1.32 UPNP E EXT NOT XML [-504] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.1.33 UPNP E NOT FOUND [-507] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.1.34 UPNP E INTERNAL ERROR [-911] . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4.2 Constants, Structures, and Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.2.3 UPnP EventType — The reason code for an event callback. . . . . . . . 17 4.2.5 Upnp SType — Represents the di?erent types of searches that can be performed using the SDK for UPnP Devices API. . . . . . . . . . . . . . . . . . . 22 4.2.6 Upnp DescType — Specifies the type of description in UpnpRegis- terRootDevice2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 4.2.7 Upnp Action Request — Returned as part of a UPNP CONTROL ACTION COMPLETE callback. . . . . . . . . . . 25 4.2.8 Upnp State Var Request — Represents the request for current value of a state variable in a service state table. . . . . . . . . . . . . . . . . . . . . . . . . . . 28 4.2.9 Upnp State Var Complete — Represents the reply for the current value of a state variable in an asynchronous call. . . . . . . . . . . . . . . . . . . . . . . . . . 30 4.2.10 Upnp Event — Returned along with a UPNP EVENT RECEIVED callback. . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.2.11 Upnp Discovery — Returned in a UPNP DISCOVERY RESULT callback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.2.12 Upnp Event Subscribe — Returned along with a UPNP EVENT SUBSCRIBE COMPLETE or UPNP EVENT UNSUBSCRIBE COMPLETE callback. . . . . . 35 4.2.13 Upnp Subscription Request — Returned along with a UPNP EVENT SUBSCRIPTION REQUEST callback. . . . . . . 37 4.2.14 UpnpVirtualDirCallbacks — The UpnpVirtualDirCallbacks struc- ture contains the pointers to file-related callback functions a device ap- plication can register to virtualize URLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 4.3 Initialization and Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 4.4 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 4.5 Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 4.6 Eventing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 4.7 Control Point HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 4.8 Web Server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92 5 Optional Tool APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97