#nop vim: set filetype=tt:;

/*
本文件属于 PaoTin++ 的一部分。
PaoTin++ © 2020~2023 的所有版权均由担子炮(dzp <danzipao@gmail.com>) 享有并保留一切法律权利
你可以在遵照 GPLv3 协议的基础之上使用、修改及重新分发本程序。
*/

///=== {
///// sync 是一个服务器同步机制，可以确保服务器已经处理完了之前发送的命令队列。
///// 假设服务器是按照顺序处理客户端发送的命令，那么因为存在网络延迟，因此客户端
///// 可能已经发送了多个命令在网络上，但还没有到达服务器，或者服务器因为繁忙所以
///// 将其放入了命令缓冲队列尚未响应。
/////
///// 但有些时候，客户端需要明确服务器是否已经处理了之前发送的命令。此时可以使用
///// 本模块。其基本原理是，通过发送别致同步符号，并请求服务器回显该符号，以等待
///// 服务器处理完之前发送的命令。如果收到了服务器的回显，则认为命令缓冲已空，并
///// 可以进行后续操作。
///// };

#var lib_sync[META] {
    {NAME}      {服务器同步}
    {DESC}      {和服务器进行同步，本模块为北侠版}
    {AUTHOR}    {担子炮}
    {NOTE}      {}
    {CONFIG}    {}
};

#nop sync.UUID 可以用来生成一个唯一的同步符号。;
#func {sync.UUID} {
    #return {@uuid{}};
};

/*
sync.Wait 可以用来和服务器进行同步，该方法有两个参数：
  1. 回调代码
     回调代码会在与服务器同步之后执行。
  2. 同步符号（可选）
     同步符号参数用来对本次同步进行唯一标识，只能由字母、数字、汉字、减号构成。
     不能包含空格、分号等在 TinTin++ 中有特殊含义的字符。
     也不能包含在正则表达式中有特殊含义的字符。
     本参数为可选值，如果省略，则无法通过 sync.Ignore 取消回调
*/
#alias {sync.Wait} {
    #local callback {%1};
    #local uuid     {%2};

    #if { {$callback} == {} } {
        errLog 回调代码不能为空;
        #return;
    };

	#if { {$uuid} == {%*{[^a-zA-Z0-9_./-]}%*} } {
		errLog 同步符号不能这么写;
		#return;
	};

    #if { "$uuid" == "" } {
        #format uuid {%U};
    };

    sync.handle {$uuid} {$callback};

    #send response R:sync-$uuid;
};

/*
   函数版的 sync.Wait 相比别名版的 sync.Wait，省略了同步符号参数要求，
   改由 sync 模块自行生成，并作为返回值返回给用户。
*/
#func {sync.Wait} {
    #local callback {%1};

    #if { {$callback} == {} } {
        errLog 回调代码不能为空;
        #return;
    };

    #local uuid {};
    #format uuid {%U};

    sync.Wait {$callback} {$uuid};

    #return {$uuid};
};

#nop 这里保存同步符号和回调代码的对应关系。;
#var gSyncHandlers {};

#alias {sync.handle} {
    #local uuid     {%1};
    #local callback {%2};
    #var {gSyncHandlers[$uuid]} {$callback};
};

#nop sync.Ignore 可以忽略指定的同步信息，将不会再触发回调代码。;
#alias {sync.Ignore} {
    #local uuid {%1};
    #unvar {gSyncHandlers[$uuid]};
};

#nop 根据服务器返回的信息，调用相应的回调代码。;
#action {^系统回馈：R:sync-%*$E} {
    #local uuid {%1};
    #local callback {$gSyncHandlers[$uuid]};
    #unvar {gSyncHandlers[$uuid]};
    #if { {$callback} != {} } {
        $callback;
    };
    #line gag;
};