Menu
▾
▴
Tree [4cf281] master / History
Allen Tse
Read Me
简体中文见后半部分
/***************************************************************************
* *
* Explicit Distribution Declaration *
* This program is not welcomed to be modified or used by, or, if *
* possible, redistributed to people who discriminate against people *
* based solely on race, gender or sexual orientation. *
* *
***************************************************************************/
/***************************************************************************
Copyright 2010 Allen Tse
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
***************************************************************************/
<General description>
EZ Comm consists a dynamic library and an executable. The library processes
network interactions while the executable handles UI and the logic of
interaction.
EZ Comm is an easy TCP/UDP communication tool displaying everything it
receives and sending everything you input. If source code is downloaded and
you want to build the application yourself, Ultimate++ is needed. Though the
interface functionalities are built upon Ultimate++, the core functionalities
are not, thus can be built separately on either Windows or Linux(POSIX).
<Simle usages>
The interface is split into two parts, local and remote. If no local
address is input, all interfaces are tried. If no local port is input,
a valid one is automatically chosen. If listening is requested, remote
address and port are not needed to be provided. When an action is requested
without necessary information, such as address or port, corresponding
input fields will be marked out.
If an address frequently sends data to another address within a period, it
may be flooding or attacking. When anti-flood is enabled, the length of this
period and the number of messages that triggers this function can both be
configured. The flooding party will be disconnected and its address will be
added to blacklist, so that within some time (the length of this period can
be configured, too) it will still be blocked.
<Files used>
Logging can be enabled. A log file is an XML file, versioned 1.0. The root
element is EZ_Comm and the file's type, program's version and link are the
element's attributes. Type's value is log (described in this paragraph), bat
(automatic mode guide file, described later) or cfg (described in the next
paragraph). Information is added as other elements and system's time will be
their attributes.
EZ Comm uses configuration file ezcomm.xml under current directory. If it
is absent, it is regarded as the first time running and the file will be
created. If a file with same name but invalid format exists, EZ Comm will
try to rename it with a number. The file's format is similar to a log file,
except that the type's value must be cfg. The program version and link
attributes of the root element are optional. If it is the first time running,
EZ Comm shows wizard window.
Wizard window shows words to help user step by step. It can be closed
anytime and shown by choosing to in Help window. If wizard window is shown
when EZ Comm shuts down, the next time it will be shown, too. This is an
element in the configuation file. The element's name is wizard.
User can switch language in Language window. It has effect instantly.
Default language is the system's language. If switched, it will be stored
in the configuration file, in element language.
<Running modes>
Three modes are supported, keyboard, file and automatic mode. Automatic
mode is only in plan phase.
In keyboard mode, what user input is sent directly in ASCII.
In file mode, user chooses a file to send. An ASCII 1 is the first byte in
the outgoing buffer. Then comes the file name, packet number and file content
length, all in separate angle brackets. And after that, the file's content is
appended. When a file is received in this mode, user is prompted to save it or
discard it. Only after a former incoming file is dealt with will another file
be prompted.
In automatic mode, a batch file is needed so that this program can work on
its own. Refer to log file format for general information except that the
type's value must be bat. The root element can have an optional attribute to
save log file. Its name is log and its value is the file's name. The program
version and link attributes are optional.
All nodes can have attribute bookmark, whose value should be
unique across the file, to mark a position in the procedure.
Elements with the names in the table below are processed. These elements
are referred to as action nodes. If and only if an action's result is
successful (refer to if description in the table below), its sub-nodes will be
processed. Note that though some attribute values are ignored, they must be
provided according to XML format.
+----------------------------------------------------------------------------+
| node name | attribute or BODY | result (or variable RESULT) |
|------------+-------------------------------+-------------------------------|
| compute | *get - variable name. That | A variable name followed by |
| | variable's value will be | a number, string, boolean, |
| | used as an operand. | or another variable name, |
| | *number - variable name when | can set the left operand. |
| | setting an number. | Converting an number to or |
| | *string - variable name when | from a string is allowed. |
| | setting a string. | RTTP_RGHT - succeeded |
| | *boolean - variable name when | RTTP_MNER - data types |
| | setting a boolean. | mismatch |
| | *operator - one of operators, | RTTP_CRER - incomplete |
| | +, -, *, / for integers. One | attributes |
| | of operators, append, find, | Variable VALUE stores final |
| | length, remove for strings. | result when not setting a |
| | (Attributes below cannot be | variable. The results of |
| | operands.) | find and length are numbers. |
| | *time - to get current time | remove sets no result. |
| | | Variable VALUE stores current |
| | *tick - to get current system | date and time. |
| | tick | Variable VALUE stores current |
| | | system tick. |
|------------+-------------------------------+-------------------------------|
| if | *get, integer, string, or | Booleans are checked against |
| | boolean - same as in compute | TRUE. Numbers are checked |
| | *operator - one of operators, | against non-zero. Refer to |
| | <, >, <=, >= for integers | comments after this table for |
| | (default is equality test) | strings. |
| | *operator - ~=, to compare | If no operators provided, |
| | strings, case insensitive | last RESULT will be used. |
| | (default is case sensitive) | If result is TRUE, sub-nodes |
| | | are processed. Otherwise |
| | | not. no RESULT is set. |
|------------+-------------------------------+-------------------------------|
| else | (Same as if) | (Same as if, except that the |
| | | result is checked against |
| | | FALSE.) |
|------------+-------------------------------+-------------------------------|
| flow | *loop - number of loops that | (No result. Sub-nodes should |
| | the sub-nodes will be | be the procedures to loop |
| | processed. | in the case of loop. Other |
| | *goto - bookmark to go to. | Other usages neglect |
| | (Default is to go out of | sub-nodes.) |
| | current loop.) | |
|------------+-------------------------------+-------------------------------|
| interact | *procedure - command line to | Variable VALUE stores the |
| | envoke. Values or get can | command's return value. |
| | be after this to append | |
| | parameters. | |
| | *get, integer, string, or | |
| | boolean - to append | |
| | characters to the command | |
| | line. Multiple settings | |
| | supported. | |
| | (Attributes below cannot be | |
| | used with procedure. And the | |
| | ones except wait cannot be | |
| | used with the ones except | |
| | wait, among following | |
| | attributes.) | |
| | *file - file name if a file | RTTP_RGHT - data or file |
| | is anticipated (EZ Comm | received. If a file is |
| | format). Blank will save | received, variable FILE |
| | original file name under | stores its name. Otherwise, |
| | running directory. | variable DATA stores data. |
| | *data - if some data is | RTTP_CRER - failed such as |
| | anticipated. Value ignored. | insufficient memory |
| | *auto - if a file or some | |
| | data is anticipated, decided | |
| | according to EZ Comm format, | |
| | i.e., ASCII 1 as first byte. | |
| | Value ignored. | |
| | *wait - in seconds. if | RTTP_NOER - timeout |
| | negative, this timing will | |
| | not be stopped by an | |
| | incoming packet. Attributes | |
| | after this are neglected. | |
|------------+-------------------------------+-------------------------------|
| log | *get or string - to append | |
| | characters to logging as | |
| | text, if logging is enabled. | |
| | *raw - if the characters need | |
| | to be stored as CDATA. | |
| | *BODY - more text logging. | |
|------------+-------------------------------+-------------------------------|
| listen | *laddress - local address | RTTP_RGHT - succeeded |
| | *lport - local port | RTTP_NOER - already listening |
| | *method = TCP or UDP(default) | RTTP_MNER - failed such as |
| | connected - bookmark to go to | binding failed |
| | when a client connected | RTTP_CRER - failed such as |
| | disconnected - bookmark to go | insufficient memory |
| | to when disconnected | |
|------------+-------------------------------+-------------------------------|
| connect | (same as listen, plus) | (same as listen, plus) |
| | raddress - remote address | If succeeded, variable |
| | rport - remote port | SESSION stores session ID. |
|------------+-------------------------------+-------------------------------|
| send | *raddress - remote address | RTTP_RGHT - succeeded |
| | for UDP | RTTP_MNER - if failed such no |
| | *rport - remote port for UDP | corresponding session ID |
| | session - session ID for TCP | RTTP_CRER - failed such as |
| | *file - file name if a file | insufficient memory |
| | is to be sent | |
| | *BODY(default is zero length) | |
| | - text if it is to be sent | |
|------------+-------------------------------+-------------------------------|
| disconnect | *session - session ID for TCP | RTTP_RGHT - succeeded |
| | (default is all sessions) | RTTP_MNER - if failed such as |
| | | no corresponding session ID |
+----------------------------------------------------------------------------+
* = optional.
Once connected, it cannot listen or connect before disconnection.
All incoming connection requests and packet are discarded if not mentioned
to receive in interact.
Numbers are stored in the type of double.
Booleans are either TRUE or FALSE.
Normal strings are checked against non-empty. The returned values RTTP_RGHT,
RTTP_NOER, RTTP_MNER, RTTP_CRER, are special strings. Their values can be
checked with numbers, equaling to 4 to 1, respectively. And the former two can
be regarded as boolean TRUE, while the latter two as FALSE, when being
checked. Operators append and find needs both left and right operands to be
strings. The right operand is appended to the left or searched within the left
respectively. Operand remove needs left operand to be a string and
right operand to be a number, which indicates the number of characters to be
removed from the string's beginning and negative numbers mean the removal
occurs at its end. Operand length needs left operand to be a string and has
no right operand.
Allen Tse
Nov. 28, 2019
/***************************************************************************
* *
* 明确发布声明 *
* 本程序不欢迎对人有种族、性别或性取向歧视的人士修改、使用，且如果 *
* 可能的话也不宜向其传播。 *
* *
***************************************************************************/
/***************************************************************************
版权 2010 Allen Tse
本文件以the Apache License, Version 2.0（以下简称授权）授权（以下中文翻译
并非官方翻译，仅供参考，表义以英文原文为准）。
您不能够以不遵守授权的方式使用文件。
您可以可以从以下地址得到授权的拷贝：
http://www.apache.org/licenses/LICENSE-2.0
除非写明由于执行法律或或同意的需要，以授权发布的软件基于“本形式”，无论
显式或隐式，都没有任何形式的保证或条件。授权中关于特定语言的许可和限制，
详见授权原文。
***************************************************************************/
<概述>
易通信包含一个动态链接库和一个可执行应用。前者负责网络收发，后者处理逻辑
与界面。
易通信是一个简单的TCP/UDP通信工具。它可以显示收到的和您输入并发送的文本。
如果下载源码自己编译，则需要使用Ultimate++。虽然界面部分是用Ultimate++建立
的，但是易通信的核心功能部分则不是，所以可以单独在Windows或Linux(POSIX)上编
译。
<简明使用>
界面分为本地和对端两部分。如果不写本地地址，则绑定所有地址；如果不写
本地端口，则自动选择一个可用的。当要求“监听”时，不必填写远端IP和端口。在被
要求进行某个动作而未提供必要信息，如地址或端口时，对应的输入框会被标示出来。
如果一个地址在一段时间内频繁向对方发送数据，则有可能是网络攻击。当打开
防止攻击功能时，多长时间内收到多少消息，是可以配置的。在被攻击时，会断开与
这个地址的通信，而且将其放入黑名单，在一段时间（这个时间长短也是可配的）内
仍然屏蔽它。
<使用的文件>
可以记录日志。日志文件的格式是xml 1.0版本。根元素是EZ_Comm，其属性有
文件的类型、程序的版本和网址。类型可以是log（本段描述）、bat（自动模式指
南文件，后面描述）或cfg（下段描述）。信息作为其它元素添加，系统时间会作
为其属性。
易通信使用当前目录下的配置文件ezcomm.xml。如果不存在，则认为是第一次
运行，生成该文件。如果有同名文件，但不是可读的格式，则会试图将其以带上一
个数字的形式进行重命名。文件格式与日志文件格式类似，不过类型应该是cfg。
程序版本和网址可以作为根元素属性，也可以没有。如果是第一次运行，会显示助
手窗口。
助手窗口引导用户逐步操作，随时可以关闭。关闭后通过帮助窗口可以再显
示。如果程序退出时助手窗口还开着，则下次启动后助手窗口还会显示。这是配置
文件中的wizard元素。
用户通过语言窗口可以切换界面语言。该配置即时生效。默认为系统语言。切
换后，保存于配置文件中的language元素。
<运行模式>
支持三种模式：键盘、文件和自动。自动模式尚在计划阶段。
在键盘模式，用户输入的文字以ASCII直接发送。
在文件模式，用户选择要发送的文件。ASCII码1位于发送缓冲的第一个字节，然后
是文件名、包序号和文件长度，每个都括在尖括号中。此后，是文件内容。此模式下接
收到一个文件时，会提示用户选择保存或丢弃。只有先收到的文件处理了之后，后收到
的文件才会产生提示。
在自动模式，需要一个批处理文件使程序可以自己运行。文件格式参考日志文件的
总体描述，只是类型取值应该是bat。根元素有可选属性指定日志文件，名称为log，取
值为文件名。程序版本和网址属性是可选的。
谢威扬
二○一九年十一月二十八日
