aardio 文档

web.rpc.externalServer 库模块帮助文档

用法说明

1、在 aardio 编写的本地软件中创建 RPC 服务端 var rpcServer = web.rpc.externalServer() rpcServer.start();

2、使用 rpcServer.getUrl("aardio.js") 取得 aardio.js 的地址, 并在网页中使用该地址加载 aardio.js

3、网页如果使用了 typescript,源码工程中添加 global.d.ts 内容如下:

declare global {

    interface aardioExternal {  
    /* 添加 external 接口导出的 aardio  函数 */
    test: (name: string,value: number) => Promise<string>; 
    }
}
export {};

4、打开远程网页则必须在 URL 中通过 rpcServerPort 参数指定 RPC 服务端口号, 必须在 JavaScript 中调用 aardio.open() 连接 RPC 服务端,并在 aardio.ready 回调中使用 RPC 函数。

如果要限制调用 aardio 函数的域名,可以这样写:

rpcServer.accessControlAllowOrigin = {
    ["https://example.com"] = true //域名后不要加斜杠
}

web.rpc 成员列表

web.rpc.externalServer

创建可在普通网页浏览器引入与 aardio 本地软件交互的 RPC 服务端
建议服务端IP保持默认值 127.0.0.1,
即可在任意网页中调用 aardio.js 并导入 aardio 对象,
可嵌入 HTTPS 网页

web.rpc.externalServer()

创建可在普通网页浏览器引入与 aardio 本地软件交互的 RPC 服务端,
可自动支持标准库 nodeJs

返回对象:webRpcExternalServerObject

webRpcExternalServerObject 成员列表

webRpcExternalServerObject.accessControlAllowOrigin

允许写入 Access-Control-Allow-Headers 响应头的站点地址。
此属性必须为 null、字符串,或者指定为一个表对象,
表的键为允许跨域调用的站点地址,值必须为 true
站点地址应使用 https://host 格式,且结尾不要有斜杠,
新的浏览器已经禁止在非 HTTPS 协议下调用本机地址,
而老版浏览器则反之

webRpcExternalServerObject.accessControlRequestPrivateNetwork

自定义 Access-Control-Request-Private-Network 响应头的值,
默认为 "true",可改为 null

webRpcExternalServerObject.callback(name,callback)

webRpcExternalServerObject.callback("/*要接收返回值的JS函数名,  
回调叁数$为RPC客户端套接字句柄  
成功result为返回值,失败err为错误信息*/",function($,result,err){  

})

webRpcExternalServerObject.doScript($,js,...)

在chrome中执行javascript代码,忽略返回值,
在js参数后可选指定多个字符串格式化参数用于调用string.form格式化代码,

参数@1指定客户端套接字句柄,
RPC服务端远程回调函数名首字符为$时,
第一个回调$参数即为当前客户端套接字句柄,
除非熟悉getActiveSocket函数导致的潜在问题,请不要省略$参数

webRpcExternalServerObject.external

webRpcExternalServerObject.external = {
    /*可以在这里指定允许chrome访问的对象和函数  
在chrome里引用虚拟的"/aardio.js"导入aardio对象即可访问这里的成员函数,  
请在调用start函数以前设置此对象*/
}

webRpcExternalServerObject.getActiveSocket()

获取RPC服务端当前活动套接字句柄
,任何触发消息处理、异步套接字处理程序的代码都有可能改变这个函数的返回值
任何时候都不推荐使用此函数

更好的替代方案是在RPC函数名前添加$字符,用于通知aardio在回调参数中添加$参数
回调$参数可以稳定可靠的获取当前套接字

webRpcExternalServerObject.getPort()

返回端口号

webRpcExternalServerObject.getUrl()

此函数可自动调用 start 函数。
参数 @1 指定资源文件路径,
转换并返回为可以通过内嵌 HTTP 服务端访问的网址。
可将此函数获取的 aardio.js 嵌入任意浏览器本地打开的网页

如果参数 @1 传入小写 http: 或 https: 开头的网址,
则返回了附加 rpcServerPort 与 rpcAasdl 参数的网址,
aardio.js 支持识别这些参数并自动初始化
远程网页如果不指定 rpcAasdl 参数,则在连接成功前只能使用 aardio.xcall 调用本地函数。
如果不指定 rpcServerPort 参数,
则必须调用 aardio.open 主动连接本地接口

webRpcExternalServerObject.http

aardio创建的HTTP服务器

返回对象:asynHttpServerObject

webRpcExternalServerObject.httpHandler

webRpcExternalServerObject.httpHandler["/test.js" ] = function(response,request,session){
    /*自定义HTTP处理程序  
键为请求的路径,值为处理函数,  
值也可以直接指定响应字符串*/
}

webRpcExternalServerObject.notify($,"method",...)

调用指定chrome函数,但不需要客户端回调反馈,

参数@1指定客户端套接字句柄,
RPC服务端远程回调函数名首字符为$时,
第一个回调$参数即为当前客户端套接字句柄,
除非熟悉getActiveSocket函数导致的潜在问题,请不要省略$参数

webRpcExternalServerObject.onClose

webRpcExternalServerObject.onClose = function($hSocket,err){
    /*一个网页窗口断开连接触发此事件*/
}

webRpcExternalServerObject.onError

webRpcExternalServerObject.onError = function($hSocket,err){
    errput(err,"chrome/rpc error");/*自定义RPC错误处理*/
}

webRpcExternalServerObject.onUrlReady

webRpcExternalServerObject.onUrlReady = function(hSocket,url){
    /*页面加载完成并且页面上的DOM内容、aardio模块都已准备就绪*/
}

webRpcExternalServerObject.publish(method,...)

主动向所有客户端发送通知
method指定网页客户端方法名,
可添加任意个调用参数

webRpcExternalServerObject.rpc

aardio创建的JSON-RPC服务端

返回对象:websocketjsonserverObject

webRpcExternalServerObject.start(端口,IP)

启动 RPC 服务端,
所有参数可选,IP默认为 127.0.0.1,
建议服务端IP保持默认值 127.0.0.1,
即可在任意网页中调用 aardio.js 并导入 aardio 对象,
可嵌入 HTTPS 网页

webRpcExternalServerObject.survey(method,...)

发起调查任务,
调用所有网页客户端的同名函数,
method指定客户端方法名,
可添加任意个调用参数

请使用callback函数指定调查结束后客户端回调的函数

webRpcExternalServerObject.ws

aardio创建的WebSocket服务器

返回对象:websocketserverObject

webRpcExternalServerObject.xcall($,"method",...)

调用chrome函数,
参数@1指定客户端套接字句柄,
RPC服务端远程回调函数名首字符为$时,第一个回调$参数即为当前客户端套接字句柄,
除非熟悉getActiveSocket函数导致的潜在问题,请不要省略$参数

在chrome的js代码使用 aardio.on("method")
添加允许aardio调用的js回调函数.

可选使用callback函数指定一个同名回调函数按收本次调用chrome的返回值

Markdown 格式