关于libupup的使用详解_总结

OS平台:ubuntu 15.04
gcc版本:version 4.9.2

下载(2016.7更新至1.6.20)

    官网link: http://pupnp.sourceforge.net/
    downdload link: https://sourceforge.net/projects/pupnp/files/
                                  https://sourceforge.net/projects/pupnp/files/latest/download?source=files

        将下载好的libupnp-1.6.20.tar.bz文件解压,进入解压后的libupnp-1.6.20目录

目录文件概览

        根目录中有一个README文件,基本上是这个库的官方介绍,包括了编译和安装说明,仔细阅读
        
        其他文件及目录:
            LISENSE--许可说明文件
            NEWS--更新和新特性
            ixml/*--xml解析源码文件说明文件的目录
            threadutil/*--线程相关
            upnp/doc/--upnp说明文档相关
            upnp/inc/--upnp头文件
            upnp/src/--upnp源文件
            upnp/sample--官方的demo

        其中,我们主要是使用upnp/目录下的文件

编译安装

        系统要求

            libpthread程序包 --由于threadutil使用了pthread线程,所以这个包要提前安装

            DOC++程序包 --编译生成说明性HTML文件(可选)
            LaTeX/TeX --编译生成说明性pdf文件(可选)

        编译

        核心库的编译

            $ cd $(LIBUPNP) 进入libupnp根目录
            $ ./configure   #默认配置下,会将include文件安在/usr/local/include/upnp目录
                    #将lib文件安装在/usr/local/lib目录下
            $ make    #编译核心库    
        
            $ make html    #编译生成html说明
            $ make pdf    #编译生成pdf说明

            一些自定义配置选项(见upnp/inc/upnpconfig.h)
            $ ./configure --enable-debug    #使能debug支持(默认下不支持)
            $ make

            $ ./configure --enable-webserver #包含mini web服务器(默认下支持)
            $ make
            #...其他参考README以及upnpconfig.h
            $ make clean    #清除所有目标文件,对象文件以及说明文件

        交叉编译

            所谓交叉编译,就是在一个系统平台上编译产生另外一种平台的可执行代码,常见的交叉编译情景是在pc-linux平台上编译arm-linux的代码

            $ ./configure --host=arm-linux #主机为arm-linux
            $ make  #将激活arm-linux-gcc编译器来编译SDK

        sample的编译(默认)

            $ ./configure --enable-samples
            $ make

        其他OS平台的编译(忽略)

        安装/卸载

        $ sudo make install #使用root身份安装
        $ sudo make uninstall #使用root身份卸载

sample的使用测试

        sample目录下的文件是与整个libupnp库来一起编译的,如果想单独编译,可以使用一个单独的工作空间来保存源代码

        sample这个小实例实现了一个虚拟的电视的设备,并相应的有一个控制点应用来对这个设备进行发现控制等

        目录结构

        下面先看一下这个目录中的文件,如果编译过库文件后应该会有相应的对象文件(*.o)
        common  该目录下主要是一些函数实现,以供linux目录下的main函数测试
        ├── sample_util.c  //一些工具函数,像是打印,解析xml等
        ├── sample_util.h
        ├── tv_ctrlpt.c    //控制点的实现
        ├── tv_ctrlpt.h
        ├── tv_device.c    //设备端的实现
        └── tv_device.h

        linux 该目录下的三个main文件通过调用common目录中的实现函数,实现三个小应用
        ├── tv_combo_main.c   //一个综合的应用,没仔细研究
        ├── tv_ctrlpt_main.c  //控制点的主函数
        └── tv_device_main.c  //设备端的主函数

        web  该目录下存放tv设备的设备描述文件,服务描述文件,设备展示文件
        ├── tvcombodesc.xml   //小综合的设备描述文件
        ├── tvcontrolSCPD.xml //设备的控制服务的描述文件
        ├── tvdevicedesc.xml  //电视设备的设备描述文件
        ├── tvdevicepres.html //设备的展示文件 ,html文件用于web服务器浏览
        └── tvpictureSCPD.xml //设备的显示服务描述文件

        编译之后,会出现三个脚本文件,不用管
            -rwxrwxr-x 1 sl sl  8278  7月  8 15:27 tv_combo*
            -rwxrwxr-x 1 sl sl  8264  7月  8 15:27 tv_ctrlpt*
            -rwxrwxr-x 1 sl sl  8264  7月  8 15:27 tv_device*
        出现一个隐藏文件.lib 该目录下存放着这个编译好的可执行文件
            sl@sl-desktop:~/Downloads/libupnp-1.6.20/upnp/sample$ ll ./.libs
            total 264
            drwxrwxrwx 2 sl sl   4096  7月  8 15:27 ./
            drwxrwxrwx 6 sl sl   4096  7月  8 15:33 ../
            -rwxrwxr-x 1 sl sl 107364  7月  8 15:27 tv_combo*
            -rwxrwxr-x 1 sl sl  74000  7月  8 15:27 tv_ctrlpt*

            -rwxrwxr-x 1 sl sl  72140  7月  8 15:27 tv_device*

       运行实验

           设备端启动

            按照说明,切换到sample目录中,      

             $ ./tv_device #启动tv设备

            显示:   

            Initializing UPnP Sdk with            //初始化upnp

                ipaddress = {NULL} port = 0
            UPnP Initialized
                ipaddress = 219.231.158.236 port = 49152                           //设备获取到的ipaddress:port
            Specifying the webserver root directory -- ./web                           //设定web服务器根目录
            Registering the RootDevice                                                 //注册根设备
                 with desc_doc_url: http://219.231.158.236:49152/tvdevicedesc.xml  //设备的设备描述文件 url
            RootDevice Registered                                         
            Initializing State Table                                                   //初始化设备的状态信息表
            udn = uuid:Upnp-TVEmulator-1_0-1234567890001                               //打印设备的udn
            Found service: urn:schemas-upnp-org:service:tvcontrol:1    //此时正在解析设备的设描述文件并且将必要的信息填充进信息状态表
            serviceId: urn:upnp-org:serviceId:tvcontrol1
            Found service: urn:schemas-upnp-org:service:tvpicture:1
            serviceId: urn:upnp-org:serviceId:tvpicture1
            State Table Initialized
            Advertisements Sent                 //设备端向整个网络发布本设备上线请求

            >>    //这里进入设备命令接收循环,等待用户输入命令(其实是只有exit),与此同时,设备的事件处理也会等待事件的到来

         控制点(CP)端启动

        开启另外一个终端,进入sample目录,

        $ ./tv_ctrlpt
        显示
            Initializing UPnP Sdk with
            ipaddress = {NULL} port = 0
            UPnP Initialized
            ipaddress = 219.231.158.236 port = 49153
            Registering Control Point
            Control Point Registered

            >>
           过一会将会发现设备,并将其添加到CP维护的设备列表中,显示可能不太一样,我屏蔽掉了cp源码中的很多不必要的打印
            ======================================================================
            ----------------------------------------------------------------------
            UPNP_DISCOVERY_SEARCH_RESULT           //打印出来的设备发现结果事件的详细信息
            ErrCode     =  UPNP_E_SUCCESS(0)       //事件成功返回
            Expires     =  100                     //超时100s
            DeviceId    =  uuid:Upnp-TVEmulator-1_0-1234567890001    //发现的设备udn
            DeviceType  =  urn:schemas-upnp-org:device:tvdevice:1    //设备的类型
            ServiceType =  
            ServiceVer  =  
            Location    =  http://219.231.158.236:49152/tvdevicedesc.xml                             //设备描述文件 url
            OS          =  Linux/3.19.0-65-generic, UPnP/1.0, Portable SDK for UPnP devices/1.6.20   //软件平台
            Ext         =  
            ----------------------------------------------------------------------
            ======================================================================



            In SampleUtil_FindAndParseService                                             //进入设备描述文件的解析过程
            Found service: urn:schemas-upnp-org:service:tvcontrol:1        //发现设备的控制服务
            serviceId: urn:upnp-org:serviceId:tvcontrol1                                 //该服务的id
            Out SampleUtil_FindAndParseService   
            Subscribing to EventURL http://219.231.158.236:49152/upnp/event/tvcontrol1...             //向设备的控制服务进行订阅注册
            Subscribed to EventURL with SID=uuid:4236f7c6-1dd2-11b2-bd40-840f340f3b3b        //已经订阅成功,订阅号SID
            In SampleUtil_FindAndParseService
            Found service: urn:schemas-upnp-org:service:tvpicture:1                                             //发现设备的显示服务
            serviceId: urn:upnp-org:serviceId:tvpicture1
            Out SampleUtil_FindAndParseService
            Subscribing to EventURL http://219.231.158.236:49152/upnp/event/tvpicture1...    //向设备的显示服务进行订阅注册
            ======================================================================
            ----------------------------------------------------------------------
            UPNP_EVENT_RECEIVED                                                            //打印关于CP对设备控制服务订阅的返回事件详细信息
            SID         =  uuid:4236f7c6-1dd2-11b2-bd40-840f340f3b3b     //唯一SID标示
            EventKey    =  0
            ChangedVars =  <e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
            <e:property>
            <Power>1</Power>           //订阅服务对象的一些控制变量,Power 值为1
            </e:property>
            <e:property>
            <Channel>1</Channel> //Channel 值为1
            </e:property>
            <e:property>
            <Volume>5</Volume>   //Volume 值为5
            </e:property>
            </e:propertyset>

            ----------------------------------------------------------------------
            ======================================================================



            In ctrl_point: handleEvent
            Subscribed to EventURL with SID=uuid:4236fef6-1dd2-11b2-bd40-840f340f3b3b    //提示已经订阅注册了设备的显示服务,唯一订阅号SID
            ======================================================================
            ----------------------------------------------------------------------
            UPNP_EVENT_RECEIVED        //打印关于CP对设备显示服务订阅的返回事件详细信息
            SID         =  uuid:4236fef6-1dd2-11b2-bd40-840f340f3b3b  //唯一的订阅号SID标示
            EventKey    =  0
            ChangedVars =  <e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
            <e:property>
            <Color>5</Color>              //服务控制变量,Color 值为5
            </e:property>
            <e:property>
            <Tint>5</Tint>               //Tint 5
            </e:property>
            <e:property>
            <Contrast>5</Contrast>       //Contrast 5
            </e:property>
            <e:property>
            <Brightness>5</Brightness>   //Brightness 5
            </e:property>
            </e:propertyset>

            ----------------------------------------------------------------------
            ======================================================================



            In ctrl_point: handleEvent
            Received Tv Control Event: 0 for SID uuid:4236f7c6-1dd2-11b2-bd40-840f340f3b3b  //提示接收到控制服务事件
            In ctrl_point: tvStateUpdate  //进入状态更新
            Tv State Update (service 0):   //更新状态表的服务0(设备的控制服务)
             Variable Name: Power New Value:'1'   //更新下面的变量值
             Variable Name: Channel New Value:'1'
             Variable Name: Volume New Value:'5'
            OUt ctrl_point: tvStateUpdate
            OUT ctrl_point: handleEvent
            Received Tv Picture Event: 0 for SID uuid:4236fef6-1dd2-11b2-bd40-840f340f3b3b  //接收到显示服务事件
            In ctrl_point: tvStateUpdate //进入状态更新函数
            Tv State Update (service 1):  //更新状态信息表中的服务1(显示服务)
             Variable Name: Color New Value:'5'
             Variable Name: Tint New Value:'5'
             Variable Name: Contrast New Value:'5'
             Variable Name: Brightness New Value:'5'
            OUt ctrl_point: tvStateUpdate
            OUT ctrl_point: handleEvent

        关于CP端用户提示命令

            Help     #显示帮助
            HelpFull #显示完整的命令帮助
            ListDev  #打印设备列
            Refresh  #清空设备链表并重新发现设备
            PrintDev      <devnum>                      #根据设备号打印具体的某一个设备,设备号是CP分配给设备链表中设备的
            PowerOn       <devnum>                    #打开电源  如>>PowerOn 1  将启动设备1的打开电源事件
            PowerOff      <devnum>                     #关闭电源  如>>PowerOff 1
            SetChannel    <devnum> <channel>      #设置频道  如>>SetChannel 1 4 将设备1设成频道4
            SetVolume     <devnum> <volume>        #设置音量
            SetColor      <devnum> <color>               #设置颜色
            SetTint       <devnum> <tint>                     #设置色彩(色度)
            SetContrast   <devnum> <contrast>           #设置对比度
            SetBrightness <devnum> <brightness>    #设置亮度
            CtrlAction    <devnum> <action>                 #控制服务动作 如>>CtrlAction 1 IncreaseChannel
            PictAction    <devnum> <action>                 #显示服务动作
            CtrlGetVar    <devnum> <varname>           #获取控制服务的变量值
            PictGetVar    <devnum> <action>                #获取显示服务的变量值
            Exit    #退出控制点应用

        CP指令举例

        >> listDev  #列出设备链表中保存的所有设备
        TvCtrlPointPrintList:
           1 -- uuid:Upnp-TVEmulator-1_0-1234567890001  #我们开启的tv设备已经在设备列表,设备号为1
           2 -- uuid:485ab6e410770000_MR                             #网络中的其他upnp设备,未知,设备号为2
        >> printdev 1  #打印设备1的详细信息
        TvCtrlPointPrintDevice:  
         Device -- 1   #设备1
            |                  
            +- UDN        = uuid:Upnp-TVEmulator-1_0-1234567890001                     #唯一设备名
            +- DescDocURL     = http://219.231.158.236:49152/tvdevicedesc.xml    #设备的描述文件url
            +- FriendlyName   = UPnP Television Emulator                                            #设备别名
            +- PresURL        = http://219.231.158.236:49152/tvdevicepres.html  #设备表达显示url,设备启动时可以在浏览器中监控设备
            +- Adver. TimeOut = 100    #设备上线发布超时时间(s)
            |                  
            +- Tv Control Service         #tv设备的控制服务
            |    +- ServiceId       = urn:upnp-org:serviceId:tvcontrol1                                    #服务ID
            |    +- ServiceType     = urn:schemas-upnp-org:service:tvcontrol:1                  #服务类型
            |    +- EventURL        = http://219.231.158.236:49152/upnp/event/tvcontrol1      #服务的事件url
            |    +- ControlURL      = http://219.231.158.236:49152/upnp/control/tvcontrol1    #服务的控制url
            |    +- SID             = uuid:bf649cea-1dd1-11b2-aad6-efcd64cf2a2b               #本CP对该服务的唯一订阅标示SID
            |    +- ServiceStateTable     #该服务的状态表,存放其控制变量
            |         +- Power      = 1
            |         +- Channel    = 1
            |         +- Volume     = 5
            |                  
            +- Tv Picture Service       #tv设备的显示服务
             +- ServiceId       = urn:upnp-org:serviceId:tvpicture1
             +- ServiceType     = urn:schemas-upnp-org:service:tvpicture:1
             +- EventURL        = http://219.231.158.236:49152/upnp/event/tvpicture1
             +- ControlURL      = http://219.231.158.236:49152/upnp/control/tvpicture1
             +- SID             = uuid:bf64ab72-1dd1-11b2-aad6-efcd64cf2a2b
             +- ServiceStateTable
                  +- Color      = 5
                  +- Tint       = 5
                  +- Contrast   = 5
                  +- Brightness = 5
        >>PowerOn 1  #打开设备1的电源

        ======================================================================
        ----------------------------------------------------------------------
        UPNP_EVENT_RECEIVED
        SID         =  uuid:55f4a0c8-1dd2-11b2-8410-ecc6ad8c3610
        EventKey    =  1
        ChangedVars =  <e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
        <e:property>
        <Power>1</Power>
        </e:property>
        </e:propertyset>

        ----------------------------------------------------------------------
        ======================================================================



        In ctrl_point: handleEvent
        Received Tv Control Event: 1 for SID uuid:55f4a0c8-1dd2-11b2-8410-ecc6ad8c3610
        In ctrl_point: tvStateUpdate
        Tv State Update (service 0):
         Variable Name: Power New Value:'1'
        OUt ctrl_point: tvStateUpdate
        OUT ctrl_point: handleEvent
        ======================================================================
        ----------------------------------------------------------------------
        UPNP_CONTROL_ACTION_COMPLETE
        ----------------------------------------------------------------------
        ======================================================================
        
        SetChannel 1 3 #设定设备1为频道3

        >> ======================================================================
        ----------------------------------------------------------------------
        UPNP_EVENT_RECEIVED
        SID         =  uuid:b1174d7a-1dd1-11b2-80a2-92f315777296
        EventKey    =  3
        ChangedVars =  <e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
        <e:property>
        <Channel>3</Channel>
        </e:property>
        </e:propertyset>

        ----------------------------------------------------------------------
        ======================================================================



        In ctrl_point: handleEvent
        Received Tv Control Event: 3 for SID uuid:b1174d7a-1dd1-11b2-80a2-92f315777296
        In ctrl_point: tvStateUpdate
        Tv State Update (service 0):
         Variable Name: Channel New Value:'3'  #设备状态表信息更新
        OUt ctrl_point: tvStateUpdate
        OUT ctrl_point: handleEvent
        ======================================================================
        ----------------------------------------------------------------------
        UPNP_CONTROL_ACTION_COMPLETE
        
        ----------------------------------------------------------------------
        ======================================================================

        >> SetVolume 1 7  #设定设备1的音量为7

        ======================================================================
        ----------------------------------------------------------------------
        UPNP_EVENT_RECEIVED
        SID         =  uuid:b1174d7a-1dd1-11b2-80a2-92f315777296
        EventKey    =  4
        ChangedVars =  <e:propertyset xmlns:e="urn:schemas-upnp-org:event-1-0">
        <e:property>
        <Volume>7</Volume>
        </e:property>
        </e:propertyset>

        ----------------------------------------------------------------------
        ======================================================================



        In ctrl_point: handleEvent
        Received Tv Control Event: 4 for SID uuid:b1174d7a-1dd1-11b2-80a2-92f315777296
        In ctrl_point: tvStateUpdate
        Tv State Update (service 0):
         Variable Name: Volume New Value:'7'
        OUt ctrl_point: tvStateUpdate
        OUT ctrl_point: handleEvent
        ======================================================================
        ----------------------------------------------------------------------
        UPNP_CONTROL_ACTION_COMPLETE
            
        ----------------------------------------------------------------------
        ======================================================================

        >>PrintDev 1  # 重新打印设备1详细信息
        TvCtrlPointPrintDevice:
         Device -- 1
            |                  
            +- UDN        = uuid:Upnp-TVEmulator-1_0-1234567890001
            +- DescDocURL     = http://219.231.158.236:49152/tvdevicedesc.xml
            +- FriendlyName   = UPnP Television Emulator
            +- PresURL        = http://219.231.158.236:49152/tvdevicepres.html
            +- Adver. TimeOut = 100
            |                  
            +- Tv Control Service
            |    +- ServiceId       = urn:upnp-org:serviceId:tvcontrol1
            |    +- ServiceType     = urn:schemas-upnp-org:service:tvcontrol:1
            |    +- EventURL        = http://219.231.158.236:49152/upnp/event/tvcontrol1
            |    +- ControlURL      = http://219.231.158.236:49152/upnp/control/tvcontrol1
            |    +- SID             = uuid:b1174d7a-1dd1-11b2-80a2-92f315777296
            |    +- ServiceStateTable
            |         +- Power      = 1
            |         +- Channel    = 3   #这里的频道和音量已经改变
            |         +- Volume     = 7
            |                  
            +- Tv Picture Service
             +- ServiceId       = urn:upnp-org:serviceId:tvpicture1
             +- ServiceType     = urn:schemas-upnp-org:service:tvpicture:1
             +- EventURL        = http://219.231.158.236:49152/upnp/event/tvpicture1
             +- ControlURL      = http://219.231.158.236:49152/upnp/control/tvpicture1
             +- SID             = uuid:b1175270-1dd1-11b2-80a2-92f315777296
             +- ServiceStateTable
                  +- Color      = 5
                  +- Tint       = 5
                  +- Contrast   = 5
                  +- Brightness = 5