RDK Documentation (Open Sourced RDK Components)
xdiscovery.h
Go to the documentation of this file.
1 /*
2  * If not stated otherwise in this file or this component's Licenses.txt file the
3  * following copyright and licenses apply:
4  *
5  * Copyright 2016 RDK Management
6  *
7  * Licensed under the Apache License, Version 2.0 (the "License");
8  * you may not use this file except in compliance with the License.
9  * You may obtain a copy of the License at
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
13  * Unless required by applicable law or agreed to in writing, software
14  * distributed under the License is distributed on an "AS IS" BASIS,
15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16  * See the License for the specific language governing permissions and
17  * limitations under the License.
18 */
19 
20 /**
21  * @file xdiscovery.h
22  * @brief The header file provides xdiscovery APIs.
23  */
24 
25 /**
26  * @defgroup XUPNP XUPnP
27  * @par XUPnP Overview:
28  * XUPnP is an implementation of the generic GUPnP framework for device discovery and using services from control points.
29  * GUPnP is a library for implementing both UPnP clients and services using GObject and LibSoup.
30  * It allows for fully asynchronous use without using threads and so cleanly integrates naturally
31  * into daemons, and supports all of the UPnP features.
32  * The GUPnP framework consists of the following libraries:
33  * - GSSDP implements resource discovery and announcement over SSDP.
34  * - GUPnP implements the UPnP specification:
35  * @n
36  * @li Resource announcement and discovery.
37  * @li Description.
38  * @li Control.
39  * @li Event notification.
40  * @li Presentation (GUPnP includes basic web server functionality through libsoup).
41  *
42  * @par Procedure involving in implementation of the GUPnP Client:
43  *
44  * - <b> Finding Services:</b>
45  * Initialize GUPnP and create a control point targeting the service type.
46  * Then we connect a signal handler so that we are notified when services we are interested in are found.
47  * @n
48  * - <b> Invoking Actions:</b>
49  * GUPnP has a set of methods to invoke actions where you pass a NULL-terminated varargs list
50  * of (name, GType, value) tuples for the in-arguments, then a NULL-terminated varargs list of
51  * (name, GType, return location) tuples for the out-arguments.
52  * @n
53  * - <b> Subscribing to state variable change notifications:</b>
54  * It is possible to get change notifications for the service state variables that have attribute sendEvents="yes".
55  *
56  * @par XUPnP Applications:
57  * @n
58  * The XUPnP daemon xdiscovery runs in system on MoCA interface.
59  * @n While starting the xdiscovery service, we create a UPnP control point with target device type as
60  * urn:schemas-upnp-org:device:BasicDevice:1.
61  * @n Once UPNP control point is added and active in the network, It search for the target device
62  * types in the network.
63  * @n The device-proxy-available Signal is emitted when any device which matches target types is found
64  * in the network and the event is handled in a callback routine.
65  * @n @n
66  * The discovery messages contains a few information about the device , Usually the device descriptions
67  * is in an XML file and it includes vendor specific information like Manufacturer, Model Name, Serial No.,
68  * URL to vendor specific web sites etc. Also it lists the services as well if any.
69  * @n @n
70  * Each service description includes a list of commands to which the service responds with its parameters and arguments.
71  * The UPnP control point subscribes for the notification if any of the service variable changes during run time.
72  * @n @n
73  * After the device is discovered in the network, the UPnP control point send an action by calling the GUPnP API
74  * gupnp_service_proxy_send_action() to retrieve device info and its capabilities.
75  * @n @n
76  * After that it add or update the device in device list using its serial number.
77  * @n @n
78  * Gateway set up : Internally XUPnP uses a script /lib/rdk/gwSetup.sh to set up the gateway in client devices.
79  * Here we sets up the routing table, DNS setting etc.
80  * @n
81  * @par An example of XUPnP Device Info in JSON format
82  * @code
83  * {
84  * "sno":"PAD200067027",
85  * "isgateway":"yes",
86  * "gatewayip":"169.254.106.182",
87  * "gatewayipv6":"null",
88  * "hostMacAddress":"84:e0:58:57:73:55",
89  * "gatewayStbIP":"69.247.111.43",
90  * "ipv6Prefix":"null",
91  * "deviceName":"null",
92  * "bcastMacAddress":"84:e0:58:57:73:59",
93  * "recvDevType":"X1",
94  * "buildVersion":"66.77.33p44d5_EXP",
95  * "timezone":"US/Eastern",
96  * "rawoffset":"-18000000",
97  * "dstoffset":"60",
98  * "dstsavings":"3600000",
99  * "usesdaylighttime":"yes",
100  * "baseStreamingUrl":"http://127.0.0.1:8080/videoStreamInit?recorderId=P0118154760",
101  * "requiresTRM":"true",
102  * "baseTrmUrl":"ws://127.0.0.1:9988",
103  * "playbackUrl":"http://127.0.0.1:8080/hnStreamStart?deviceId=P0118154760&DTCP1HOST=127.0.0.1&DTCP1PORT=5000",
104  * "dnsconfig":"search hsd.tvx.comcast.net;nameserver 75.75.75.75;nameserver 75.75.76.76;nameserver 69.252.80.80;",
105  * "hosts":"69.247.111.43 pacexg1v3;",
106  * "systemids":"channelMapId:1901;controllerId:3415;plantId:0;vodServerId:70001",
107  * "receiverid":"P0118154760"
108  * }
109  * @endcode
110  *
111  * @ingroup XUPNP
112  *
113  * @defgroup XUPNP_XDISCOVERY XUPnP XCal-Discovery
114  * Describe the details about XUPnP XCal-Discovery specifications.
115  * @ingroup XUPNP
116  *
117  * @defgroup XUPNP_XDISCOVERY_FUNC XUPnP XCal-Discovery Functions
118  * Describe the details about XUPnP XCal-Discovery specifications.
119  * @ingroup XUPNP_XDISCOVERY
120  */
121 
122 #ifndef XDISCOVERY_H
123 #define XDISCOVERY_H
124 
125 #define _IARM_XUPNP_NAME "XUPnP" /*!< Method to Get the Xupnp Info */
126 #define IARM_BUS_XUPNP_API_GetXUPNPDeviceInfo "GetXUPNPDeviceInfo" /*!< Method to Get the Xupnp Info */
127 
128 #endif // XDISCOVERY_H