Coremail2.0API使用手册(sms)

CoreMail2.0 Standard Edition
Doc Version 1.0
API使用手册（邮件到达专用）
Tebie Limited
香港普智资讯科技有限公司
2002.11
COREMAIL2.0 C API
1.Coremail API工作结构图
Coremail API 在系统中的位置图。

2.API配置文件说明
在Coremail系统配置中，apisvr.conf是配置Coremail API的系统文件。

具体配置如下：
[Global]
User="coremail" #执行程序的用户
Unlimit="1" #系统执行程序是否有Unlimit设置
Daemon="0" #是否为后台执行（1—yes,0—no）
DebugLevel="0" #是否为Debug级别日志
LogFile="/home/coremail/logs/apisvr.log" #普通日志文件路径
ErrorLogFile="/home/coremail/logs/apisvrerr.log" #出错日志文件路径
[SERVER SETTING]
Port="2700" #服务监听端口
[COMMAND SETTING]
Port="2702" #服务命令端口
[CLIENT SETTING]
ServerIP="127.0.0.1" #API安装服务器的IP地址
[welcome] #如果有此配置段则用API注册用户成功后发欢迎信，filename指定欢迎信模版
filename= “欢迎信模版路径”
3.CoreMail 系统提供的API包括功能
1 . 增加新用户
2 . 修改用户资料
3 . 删除用户
4 . 读取用户资料
5 . 检查用户是否存在
6 . 登陆用户
7 . 用户退出登陆
8 . 提供"临时空间"，让CGI存放session信息
9 . 让CGI读取自己存放的session信息
10. 检查session是否已经过期
11. 刷新session，防止session过期
12. 认证用户密码
13. 扫描病毒邮件
14. 增加虚拟域
15. 修改虚拟域
16. 删除虚拟域
17. 检查虚拟域信息
18. 查询域用户总数
19. 给用户过滤器添加过滤规则
API 以网络接口(socket)的方式提供，即API 程序把有关功能发送给CoreMail 的API server, 然后由server 执行具体任务。

4.API 函数的运行步骤
1.. 用API_Connect 函数连接CoreMail 系统，并建立上下文结构
2.. 用API_CreateUser, API_ChangeUser, API_DelUser等函数执行具体任务
3.. 用API_Close 关闭连接。

这一步十分重要。

范例：
5.API结构和通用函数介绍
上下文结构：APIContext
APIContext是记录了与API Server 之间连接信息的变量。

在API_Connect 成功以后，以后所有的API 操作都通过这个变量进行。

char m_szUserID[APIUSERIDLEN] ; 操作用户名字，包括'\0'
const char * m_lpszParam; 操作的参数，如果没有参数，可以是空字串""，
或者空指针NULL
如果有参数，参数格式：key1=val1&key2=val2.....
注：要按照生成 URL 的规则来生成参数
“key1=val1&key2=val2”，即 keyX 和 valX 中的
特殊字符要按照生成 URL 的方式进行编码。

（生
成 URL 的规则在 RFC1738 中定义。

例如，若
password=123&%$#，调用API 时的参数应为
“password=123%26%25%24%23”。

）
int m_nRtnCode; /* Result */ 返回的结果代码，在api.h 中定义，正常时应为
API_OK。

char * m_lpszInfo; /* Result */ 返回的结果内容，
（当执行
API_Close的时候，会自动释放该变量所申请的
内存空间）
/* Error Info */
发生错误的时候，存放出错信息。

char
m_szErrInfo[APIRTNINFOLEN];
∙API_RTCODE API_Connect(const char * szHost, unsigned short uPort, APIContext *pContext)
功能：连接API Server
入口参数：
szHost: APIServer 所在的主机IP
uPort: APIServer 采用的端口号
pContext: 存放连接信息上下文的变量
返回值类型：
API_RTCODE: 返回值，表示是否成功。

成功：API_OK
在pContext所指的Context中，进行初始化，并建立连接信息
∙API_RTCODE API_Close(APIContext * pContext);
功能：释放连接，并释放执行中申请的资源
入口参数：
pContext: 由API_Connect连接时，建立的连接信息上下文
返回值类型：
API_RTCODE 表示是否成功。

成功：API_OK
∙API_RTCODE API_Write(APIContext * pContext);
∙API_RTCODE API_Read(APIContext * pContext);
这两个函数用于下面的功能函数中发送请求和接受返回值用，CGI用户并不需要直接调用
6.功能函数介绍
API_RTCODE API_ChangeUser(APIContext * pContext);
功能：修改用户资料
入口参数：
pContext的m_szUserID中，必须填写要修改资料的用户的名字，格式为account@domain或者account，在没有@domain的时候，系统使用默认的域。

pContext的m_lpszParam要指向填有用户修改资料内容的字符串，密码是否加密的
规则和API_CreateUser的规则一样，
例子: 要修改用户的密码和真名
"password=0Mu6f9U6xoaLU&crypted=1&truename=hahaha"
要修改用户的smsaddr属性（开通或者取消邮件到达通知功能）“smsaddr=139********”
返回值类型：
API_RTCODE 表示操作成功与否，成功返回API_OK
●API_RTCODE API_GetUserInfo(APIContext * pContext);
功能：读取用户资料
入口参数：
pContext的m_szUserID中，必须填写要获取资料的用户的名字，格式为account@domain或者account，在没有@domain的时候，系统使用默认的域。

pContext的m_lpszParam填写要获得哪些资料，
例如要获得密码和真名
"password&name"
例如要取得用户的smsaddr
“smsaddr”
返回值类型：
API_RTCODE 表示操作成功与否，成功返回API_OK
如果成功，则在pContext的m_lpszInfo中返回要查找的资料，例如要获得密码和
真名，就返回
"password=123456&truename=hahaha"
“smsaddr=139********”
●API_RTCODE API_AddFilter(APIContext * pContext);
功能：给用户过滤器增加一条过滤规则
入口参数：
pContext的m_szUserID为用户名。

pContext的m_lpszParam的内容是：过滤规则字符串，格式见相关的文档。

例如：增加一过滤规则名为sms，执行本规则后还继续执行下一条规则，内容为“对所有到达的邮件转到手机只发送邮件主题”，m_lpszParam为：
name=sms&active=1&continue=1&togsm_active=1
7.API出错信息
API_OK = 0, 成功
API_CONNECT = 1, 网络连接错误
API_CLOSE = 2, 网络关闭错误
API_WRITE = 3, 网络写操作错误
API_READ = 4, 网络读操作错误
API_NOMEM = 5, 内存不足够
API_APPL YUDIDERR = 6, 申请与UDServer的连接资源失败
API_GETUDIDCLIERR = 7, 与UDServer的连接错误
API_USEREXIST = 8, 用户已经存在
API_UIDINVALID = 9, 用户名字错误
API_DELLDAPERR = 10, 从LDAP中删除用户时出错
API_ADDLDAPERR = 11, 从LDAP中增加用户时出错
API_NEEDPASSWD = 12, 需要输入密码
API_NEEDREGIP = 13, 需要输入注册时候的IP地址
API_NEWPROERR = 14, 在CoreMail系统中建立用户记录错误API_DELPROERR = 15, 在CoreMail系统中删除用户记录错误API_SETATTRERR = 16, 在CoreMail系统中设置用户属性错误API_GETATTRERR = 17, 在CoreMail系统中读取用户属性错误API_DELATTRERR = 18, 在CoreMail系统中删除用户属性错误
API_USRNOTFOUND = 19, 用户不存在
API_DOMAINNOTEXIST = 20, 域不存在
API_ERRINNET = 21, 网络错误
API_ERRGETMAILINFO = 22, 读取信件内容错误
API_ERRDELLETTER = 23, 删除信件错误
API_TIMEOUT = 24, 连接Server超时
API_ERRLOGOUT = 25, 用户退出登陆错误
API_BUSY = 26, 系统忙，没有空闲线程工作
API_SESNETERR = 27, 连接session server错误
API_SESIDNOTFOUND = 28, session id在session server里面没有找到API_HASBADENTRY = 29, 用户的注册过程被中断
API_FILTER_FORMAT_ERROR = 43, 过滤器规则格式不对
API_OTHER_ERROR, 其他错误
8.Coremail 2.0标准属性表
Coremail 属性表包括各种用户信息，开发人员在应用时应严格按照范例进行，以免对用户造成不良影响。

表中所列各项属性为Coremail UD模块存储内容, 客户端可以通过Coremail API 完成对属性的修改。