1.发现阶段
/*
*函数含义: 控制点用于寻找设备(控制点采用SSDP协议多播寻找,设备采用SSDP协议单播响应)
*输入参数:
* @param UpnpClient_Handle Hnd : 控制点执行Upnp 设备查询的一个句柄
* @param int Mx : 等待响应的时间(秒) Mx值介于MAX_SEARCH_TIME、
*MIN_SEARCH_TIME之间(可包含边界值),否则要强制性的设置最大或者最小
* @param const char* Target:控制点搜索Upnp设备一个目标(这个目标是用Upnp1.0规
* 范定义)
* @param const void* Cookie:当回调函数被调用时候,传递的用户数据
*返回值:
* 返回值是一个整型变量,定义在Upnp.h中
* UPNP_E_FINISH: Upnp的SDK未加载
* UPNP_E_SUCCESS: 操作正常的完成
* UPNP_E_INVALID_HANDLE: 控制点句柄是一个非法的句柄
* UPNP_E_INVALID_PARAM:查找的目标为空,即没有搜索到可以连接的Upnp设备
* 备注:
* 查询到的Upnp设备或者控制点句柄都会放到HandleTable[] 这个数组中去
*/
int UpnpSearchAsync(UpnpClient_Handle Hnd,int Mx,const char* Target, const void* Cookie )
/*
*函数含义: Upnp设备广播设备上线(向周围的server或者Upnp设备发送发现通告,告诉它们我
* 这个Upnp设备已经注册上线了,可以搜索到或者可以开始控制我了)
*输入参数:
* @param UpnpDevice_Handle Hnd : 发送广播通告的Upnp 设备的一个句柄
* @param int Exp: 通告的生命时间(秒),通告过期后,设备会向网络广播新的通告
*返回值:
* 返回值是一个整型变量,定义在Upnp.h中
* UPNP_E_FINISH: Upnp的SDK未加载
* UPNP_E_SUCCESS: 操作正常的完成
* UPNP_E_INVALID_HANDLE: Upnp设备句柄是一个非法的句柄
* UPNP_E_OUTOF_MEMORY: 没有足够的资源提供发送一个新的通告
*备注:
* Upnp设备的广播实质上是通过向ssdp_server传递参数调用它的AdvertiseAndReply来
* 进行广播出去
*/
int UpnpSendAdvertisement(UpnpDevice_Handle Hnd, int Exp)
2.控制阶段
/*
*函数含义: 控制点查询另一台Upnp设备的一个服务状态变量的状态
*输入参数:
* @param UpnpClient_Handle Hnd: 控制点的一个句柄
* @param const char *ActionURL_const: 被查询Upnp设备的一个服务的URL
* @param const char *VarName_const: 需要查询的那个状态变量的状态名
* @param DOMString *StVar: 用来存储状态变量值的一个指针,SDK负责分配这个字串,调用者需调用ixmlFreeDOMString.进行释放
*输出参数:
* 借助StVar将Upnp设备得到响应状态的一个string
*返回值:
* 返回值是一个整型变量,定义在Upnp.h中
* UPNP_E_FINISH: Upnp的SDK未加载
* UPNP_E_SUCCESS: 操作正常的完成
* UPNP_E_INVALID_HANDLE:控制点句柄是一个非法的句柄
* UPNP_E_INVALID_URL: 被查询Upnp设备的一个服务的URL非法
* UPNP_E_INVALID_DESC: XML文档未被找到或者XML文档描述非法
* UPNP_E_INVALID_PARAM: StVar指针非法或者VarName、ActionURL为空
* UPNP_E_OUTOF_MEMORY: 资源不足,无法完成存在的操作
* UPNP_SOAP_E_INVALID_VAR: 对于Upnp设备来说给予的变量是非法的
*备注:
* 它是请求控制中变量请求
* 实质上是利用SOAP协议调用SoapGetServiceVarStatus函数,通过SOAP响应发送一个xml
* 格式的变量状态请求去进行解析XML
*/
int UpnpGetServiceVarStatus(UpnpClient_Handle Hnd,const char *ActionURL_const,
const char *VarName_const,DOMString *StVar)
/*
*函数含义: 控制点异步查询另一台Upnp设备的一个服务状态变量的状态
*备注:
* 它跟上一个函数功能一样吗、,只是用到了回调函数,通过fun的回调将传递的用户数据
* 保存在Cookie
*/
int UpnpGetServiceVarStatusAsync(UpnpClient_Handle Hnd,const char *ActionURL_const,const char *VarName_const,Upnp_FunPtr Fun,const void *Cookie_const)
/*
*函数含义: 控制点通过发送一个消息改变Upnp设备一个服务的变量状态的状态值
*输入参数:
* @param UpnpClient_Handle Hnd: 控制点发送Action的一个句柄
* @param const char *ActionURL_const: Upnp设备的一个服务的URL
* @param const char *ServiceType_const: service的类型
* @param const char *DevUDN_const: 这个参数一般被忽视或者置NULL 用来定义一个
* 设备
* @param Document *Action: 定义Action的名称
* @param IXML_Document **RespNodePtr:用来响应这个action的一个DOM文档,SDK负责
* 分配这个文档,调用者在使用完文档需调用ixmlFreeDOMString进行释放
*输出参数:
* 借助RespNodePtr将Upnp设备得到响应action的一个DOM文档
*返回值:
* 返回值是一个整型变量,定义在Upnp.h中
* UPNP_E_FINISH: Upnp的SDK未加载
* UPNP_E_SUCCESS: 操作正常的完成
* UPNP_E_INVALID_HANDLE:控制点句柄是一个非法的句柄
* UPNP_E_INVALID_URL: 被查询Upnp设备的一个服务的URL非法
* UPNP_E_INVALID_ACTION: Action非法
* UPNP_E_INVALID_DEVICE: DevUDN设备非法
* UPNP_E_OUTOF_MEMORY: 资源不足,无法完成存在的操作
* UPNP_E_INVALID_PARAM: ServiceType, Action, ActionUrl, or RespNode 是非法指
* 针
*备注:
* 它是请求控制中动作请求
* 实质上是利用SOAP协议调用SoapSendAction函数,发送一个xml格式去进行解析XML
*/
int UpnpSendAction(UpnpClient_Handle Hnd,const char *ActionURL_const,
const char *ServiceType_const,const char *DevUDN_const,IXML_Document *Action,
IXML_Document **RespNodePtr)
/*
*函数含义: 控制点通过发送一个消息改变Upnp设备一个服务的变量状态的状态值
* (Ation行为不完成,这个异步调用就会一直做下去)
*备注:
* 跟上面的函数类型,就是在DOM Document多了一个SOAP的header
* header为空还是会掉用UpnpSendAction,不为空调用SoapSendActionEx(就是在XML中多了对
* headre的处理)
*/
int UpnpSendActionEx(UpnpClient_Handle Hnd,const char *ActionURL_const,
const char *ServiceType_const,const char *DevUDN_const,IXML_Document *Header,
IXML_Document *Action,IXML_Document **RespNodePtr)
/*
*函数含义: 控制点通过发送一个消息改变Upnp设备一个服务的变量状态的状态值
* (Ation行为不完成,这个异步调用就会一直做下去,同时通过回调函数将响应保存)
*备注:
* 通过回调函数Fun将得到的响应保存
*/
int UpnpSendActionExAsync(UpnpClient_Handle Hnd,const char *ActionURL_const,
const char *ServiceType_const,const char *DevUDN_const,IXML_Document *Header,
IXML_Document *Act,Upnp_FunPtr Fun,const void *Cookie_const)
