Skip to content

Commit

Permalink
Merge pull request #1186 from jerry-0824/branch-translate-code-comments
Browse files Browse the repository at this point in the history 
Translate code comments from Chinese into English.
  • Loading branch information
@windcbf
windcbf authored Sep 14, 2024
2 parents ef3355c + a66c505 commit c817757
Show file tree
Hide file tree
Showing 11 changed files with 241 additions and 184 deletions.
164 changes: 95 additions & 69 deletions agent/main/export.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,23 @@ func deepCopyCString(c_str *C.char) string {
return strings.Clone(goStr)
}

// 释放NHPSDK产生的字符串缓冲区内存
// Release the memory of the string buffer generated by NHPSDK.
//
//export nhp_free_cstring
func nhp_free_cstring(ptr *C.char) {
C.free(unsafe.Pointer(ptr))
}

// 初始化nhp_agent实例的工作目录路径：workingdir/etc/下为需要读取的配置文件，workingdir/logs下将生成日志文件
// 输入：
// workingDir：agent工作目录路径
// Initialization of the nhp_agent instance working directory path:
// The configuration files to be read are located under workingdir/etc/,
// and log files will be generated under workingdir/logs/.
//
// Input:
// workingDir: the working directory path for the agent
// logLevel: 0: silent, 1: error, 2: info, 3: debug, 4: verbose
// 返回：
// agent实例是否初始化成功
//
// Return:
// Whether agent instance has been initialized successfully.
//
//export nhp_agent_init
func nhp_agent_init(workingDir *C.char, logLevel C.int) bool {
Expand All @@ -58,7 +62,7 @@ func nhp_agent_init(workingDir *C.char, logLevel C.int) bool {
return true
}

// 同步停止并释放nhp_agent
// Synchronously stop and release nhp_agent.
//
//export nhp_agent_close
func nhp_agent_close() {
Expand All @@ -70,10 +74,16 @@ func nhp_agent_close() {
gAgentInstance = nil
}

// 读取workingdir/etc下所写入的用户信息、资源信息、服务器信息等配置文件，并异步启动循环敲门子线程
// 输入：无
// 返回：
// -1：未初始化错误，>=0：调用时敲门子线程请求敲门的资源个数（敲门资源会随workingdir/etc/resource.toml中的配置改动而同步变更）
// Read the user information, resource information, server information,
// and other configuration files written under workingdir/etc,
// and asynchronously start the loop knocking thread.
//
// Input: None
//
// Return:
// -1: Uninitialized error
// >=0: The number of resources requested to knock by the knocking thread at the time of the call
// (knocking resources will be synchronized with changes in the configuration in workingdir/etc/resource.toml).
//
//export nhp_agent_knockloop_start
func nhp_agent_knockloop_start() C.int {
Expand All @@ -85,7 +95,7 @@ func nhp_agent_knockloop_start() C.int {
return C.int(count)
}

// 同步停止循环敲门子线程
// Synchronously stop the loop, knock-on sub thread.
//
//export nhp_agent_knockloop_stop
func nhp_agent_knockloop_stop() {
Expand All @@ -96,14 +106,16 @@ func nhp_agent_knockloop_stop() {
gAgentInstance.StopKnockLoop()
}

// 设置agent所代表的用户信息
// 输入：
// userId：用户名标识（可选，但不建议留空）
// devId：设备标识（可选）
// orgId：公司或组织标识（可选）
// userData：与后端服务需要对接的额外字段（json格式字符串，可选）
// 返回：
// 用户信息是否设置成功
// Setting agent's represented user information
//
// Input:
// userId: User identification (optional, but not recommended to be empty)
// devId: Device identification (optional)
// orgId: Organization or company identification (optional)
// userData: Additional fields required to interface with backend services (json format string, optional)
//
// Return:
// Whether the user information is set successfully
//
//export nhp_agent_set_knock_user
func nhp_agent_set_knock_user(userId *C.char, devId *C.char, orgId *C.char, userData *C.char) bool {
Expand All @@ -124,15 +136,18 @@ func nhp_agent_set_knock_user(userId *C.char, devId *C.char, orgId *C.char, user
return true
}

// 向agent添加一个NHP服务器信息，供敲门使用（agent可以向多个NHP服务器发起不同的敲门请求）
// 输入：
// pubkey：NHP服务器公钥
// ip：NHP服务器ip地址
// host：NHP服务器域名（如果设置域名，则ip项为可选）
// port：NHP服务器工作端口号（如果设置为0，将采用默认62206端口）
// expire：NHP服务器公钥过期时间（单位：epoch秒，设为0则为永久）
// 返回：
// 服务器信息是否添加成功
// Add an NHP server information to the agent for use in knocking on the door
// (the agent can initiate different knocking requests to multiple NHP servers).
//
// Input:
// pubkey: Public key of the NHP server
// ip: IP address of the NHP server
// host: Domain name of the NHP server (if a domain name is set, the ip item is optional)
// port: Port number for the NHP server to operate (if set to 0, the default port 62206 will be used)
// expire: Expiration time of the NHP server's public key (in epoch seconds, set to 0 for permanent)
//
// Return:
// Whether the server information has been successfully added.
//
//export nhp_agent_add_server
func nhp_agent_add_server(pubkey *C.char, ip *C.char, host *C.char, port C.int, expire int64) bool {
Expand Down Expand Up @@ -161,9 +176,10 @@ func nhp_agent_add_server(pubkey *C.char, ip *C.char, host *C.char, port C.int,
return true
}

// 删除agent中的NHP服务器信息
// 输入：
// pubkey：NHP服务器公钥
// Delete NHP server information from the agent
//
// Input:
// pubkey: NHP server public key
//
//export nhp_agent_remove_server
func nhp_agent_remove_server(pubkey *C.char) {
Expand All @@ -177,13 +193,16 @@ func nhp_agent_remove_server(pubkey *C.char) {
gAgentInstance.RemoveServer(deepCopyCString(pubkey))
}

// 向agent添加一个资源信息，供敲门使用（agent可以对不同资源发起敲门请求）
// 输入：
// aspId：认证服务商标识
// resId：资源标识
// serverAddr：NHP服务器ip地址或域名（管理该资源的NHP服务器）
// 返回：
// 资源器信息是否添加成功
// Please add a resource information for the agent to use for knocking on the door
// (the agent can initiate a knock-on request for different resources)
//
// Input:
// aspId: Authentication Service Provider Identifier
// resId: Resource Identifier
// serverAddr: NHP server IP address or domain name (the NHP server managing the resource)
//
// Return:
// Whether the resource information has been added successfully
//
//export nhp_agent_add_resource
func nhp_agent_add_resource(aspId *C.char, resId *C.char, serverAddr *C.char) bool {
Expand All @@ -204,10 +223,11 @@ func nhp_agent_add_resource(aspId *C.char, resId *C.char, serverAddr *C.char) bo
return err == nil
}

// 删除agent中的资源信息
// 输入：
// aspId：认证服务商标识
// resId：资源标识
// Delete resource information from the agent
//
// Input:
// aspId: Authentication Service Provider Identifier
// resId: Resource Identifier
//
//export nhp_agent_remove_resource
func nhp_agent_remove_resource(aspId *C.char, resId *C.char) {
Expand All @@ -222,24 +242,27 @@ func nhp_agent_remove_resource(aspId *C.char, resId *C.char) {
gAgentInstance.RemoveResource(deepCopyCString(aspId), deepCopyCString(resId))
}

// agent为访问资源向资源所在服务器发起单次敲门请求
// 输入：
// aspId：认证服务商标识
// resId：资源标识
// serverAddr：NHP服务器ip地址或域名（管理该资源的NHP服务器）
// 返回：
// 服务器的回应消息（json格式字符串缓冲区指针）：
// "errCode"：错误码（字符串，"0"表示成功）
// "errMsg"：错误消息（字符串）
// "resHost"：资源服务器地址（"resHost"：{"服务器名称1":"服务器主机名1", "服务器名称2":"服务器主机名2", ...}）
// "opnTime"：开门时长（整数，单位秒）
// "aspToken"：认证服务商认证后产生的token（可选）
// "agentAddr"：NHP服务器视角下agent的ip地址
// "preActs"：与资源的预连接信息（可选）
// "redirectUrl"：http跳转链接（可选）
//
// 调用前需要调用nhp_agent_add_server，将NHP服务器公钥、地址等信息加入agent
// 调用者负责调用nhp_free_cstring释放返回的char*指针
// The agent initiates a single knock on the door request to the server hosting the resource
//
// Input:
// aspId: Authentication service provider identifier
// resId: Resource identifier
// serverAddr: NHP server IP address or domain (the NHP server managing the resource)
//
// Returns:
// The server's response message (json format string buffer pointer):
// "errCode": Error code (string, "0" indicates success)
// "errMsg": Error message (string)
// "resHost": Resource server address ("resHost": {"Server Name 1":"Server Hostname 1", "Server Name 2":"Server Hostname 2", ...})
// "opnTime": Door opening duration (integer, in seconds)
// "aspToken": Token generated after authentication by the ASP (optional)
// "agentAddr": Agent's IP address from the perspective of the NHP server
// "preActs": Pre-connection information related to the resource (optional)
// "redirectUrl": HTTP redirection link (optional)
//
// It is necessary to call nhp_agent_add_server before calling,
// to add the NHP server's public key, address, and other information to the agent
// The caller is responsible for calling nhp_free_cstring to release the returned char* pointer
//
//export nhp_agent_knock_resource
func nhp_agent_knock_resource(aspId *C.char, resId *C.char, serverAddr *C.char) *C.char {
Expand Down Expand Up @@ -285,14 +308,17 @@ func nhp_agent_knock_resource(aspId *C.char, resId *C.char, serverAddr *C.char)
return ret
}

// agent明确告知NHP服务器退出自身到该资源的访问权限
// 输入：
// aspId：认证服务商标识
// resId：资源标识
// serverAddr：NHP服务器ip地址或域名（管理该资源的NHP服务器）
// 返回：
// 是否成功退出
// 调用前需要调用nhp_agent_add_server，将NHP服务器公钥、地址等信息加入agent
// The agent explicitly informs the NHP server to exit its access permission to the resource.
//
// Input:
// aspId: Authentication Service Provider Identifier
// resId: Resource Identifier
// serverAddr: NHP server IP address or domain name (the NHP server managing the resource)
//
// Return:
// Whether the exit was successful
//
// It is necessary to call nhp_agent_add_server before calling, to add the NHP server's public key, address, and other information to the agent.
//
//export nhp_agent_exit_resource
func nhp_agent_exit_resource(aspId *C.char, resId *C.char, serverAddr *C.char) bool {
Expand Down
19 changes: 10 additions & 9 deletions agent/sdkdemo/nhp-agent-demo.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,26 +3,27 @@
#include "nhp-agent.h"

int main() {
// 初始化nhp_agent，一个进程只能有一个nhp_agent单例
// Initialize nhp_agent, only one nhp_agent singleton is allowed per process.
nhp_agent_init(".", 3);

// 设置敲门的用户信息
// Set the user information for the knock-on-the-door feature.
nhp_agent_set_knock_user("zengl", NULL, NULL, NULL);

// 设置nhp服务器信息
// 如果已经存在server的配置文件，nhp_agent_add_server调用可以省略
// 时间戳日期可见 https://unixtime.org/
// Set NHP server information
// If there is already a configuration file for the server, the call to nhp_agent_add_server can be omitted
// Timestamp date is visible at https://unixtime.org/
nhp_agent_add_server("replace_with_actual_publickeybase64", "192.168.1.66", NULL, 62206, 1748908471);

// 向服务器发送请求访问资源example/demo，返回信息为json格式字符串
// 注：此处的资源信息为独立输入，与配置文件中已保存的资源信息无关
// Send a request to the server to access the resource example/demo, and return information in the form of a JSON format string
// Note: The resource information here is an independent input, and is unrelated to the resource information saved in the configuration file
char *ret = nhp_agent_knock_resource("example", "demo", "192.168.1.66");
printf("knock return: %s\n", ret);

// 立即关闭agent对example/demo资源的访问，如果不调用，则访问权限会在开门时长经过后自行关闭
// Immediately close the agent's access to the example/demo resources,
// if not invoked, access permission will automatically close after the door opening duration has passed.
nhp_agent_exit_resource("example", "demo", "192.168.1.66");

// 关闭并释放nhp_agent
// Turn off and release nhp_agent.
nhp_agent_close();
return 0;
}
Expand Down
8 changes: 4 additions & 4 deletions core/device.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ func (d *Device) NextCounterIndex() uint64 {
return atomic.AddUint64(&d.counterIndex, 1)
}

// 异步多通道处理
// Asynchronous multi-channel processing.
func (d *Device) msgToPacketRoutine(id int) {
defer d.wg.Done()
defer log.Info("msgToPacketRoutine %d: quit", id)
Expand Down Expand Up @@ -257,7 +257,7 @@ func (d *Device) msgToPacketRoutine(id int) {
}
}

// 同步线性处理
// Synchronous linear processing.
func (d *Device) MsgToPacket(md *MsgData) (mad *MsgAssemblerData, err error) {
defer func() {
if x := recover(); x != nil {
Expand Down Expand Up @@ -303,7 +303,7 @@ func (d *Device) MsgToPacket(md *MsgData) (mad *MsgAssemblerData, err error) {
return mad, nil
}

// 异步多通道处理
// Asynchronous multi-channel processing.
func (d *Device) packetToMsgRoutine(id int) {
defer d.wg.Done()
defer log.Info("packetToMsgRoutine %d: quit", id)
Expand Down Expand Up @@ -416,7 +416,7 @@ func (d *Device) packetToMsgRoutine(id int) {
}
}

// 同步线性处理
// Synchronous linear processing.
func (d *Device) PacketToMsg(pd *PacketData) (ppd *PacketParserData, err error) {
defer func() {
if x := recover(); x != nil {
Expand Down
Loading

0 comments on commit c817757

Please sign in to comment.