Coremail 40 高级API使用手册Java版.docx

Coremail 40 高级API使用手册Java版.docx

《Coremail 40 高级API使用手册Java版.docx》由会员分享，可在线阅读，更多相关《Coremail 40 高级API使用手册Java版.docx（33页珍藏版）》请在冰豆网上搜索。

Coremail40高级API使用手册Java版

版权声明

本文档版权归盈世信息科技（北京）有限公司所有，并保留一切权利。

未经书面许可，任何公司和个人不得将此文档中的任何部分公开、转载或以其他方式散发给第三方。

否则，必将追究其法律责任。

免责声明

本文档仅提供阶段性信息，所含内容可根据产品的实际情况随时更新，恕不另行通知。

如因文档使用不当造成的直接或间接损失，本公司不承担任何责任。

文档更新

本文档由盈世信息科技（北京）有限公司于2013年5月最后修订。

公司网站

http:

//www.C

销售咨询热线400-000-1631

技术支持热线400-888-5422

A、文档修改记录

版本

修改日期

修改人员

修改记录

B、文档审核记录

版本

审核日期

审核人员

审核记录

1Coremail4.0API通用函数说明

APIContext类提供一个工厂方法，产生一个的客户端连接IClient类型的实例，即API客户端对象。

客户端对象可以进行多次调用APIServer的方法，进行操作，操作完成后客户端请求对象IClient使用close方法关闭连接。

同时，IClient类型的实例操作通常返回一个APIContext类型的对象，它记录客户端与APIServer之间的连接信息。

可以通过APIContext.getRetCode以及APIContext.getResult等方法，获取IClient调用APIServer所得的结果。

以下为APIContext所提供的方法：

1.1getClient（连接APIServer使用的socket）

publicstaticfinalIClientgetClient（.Socketsocket）

throwsjava.io.IOException

功能：

根据socket获取API客户对象，客户对象可以进行多次API操作，

操作完成后请使用IClient.close（）来关闭连接。

请注意,每个client（socket）只能在一个thread中使用,如果需要并发请为每个thread申请单独的连接

入口参数：

socket连接APIServer使用的socket

返回值类型：

客户对象

抛出异常类型：

java.lang.NullPointerException：

当传入的socket为null

java.io.IOException

1.2getRetCode（获取操作的返回值）

publicfinalintgetRetCode（）

功能：

获取操作的返回值

返回值类型：

使用类的静态常量定义（例如：

publicstaticfinalintRC_NORMAL），各自的含义为：

RC_NORMAL：

操作成功

RC_ASSWORD_ERR：

用户密码错误

RC_SES_ERRORSession：

错误

RC_SESID_NOT_FOUND：

SessionID不存在或已经过时

RC_USER_EXIST：

用户已存在

RC_USER_NOT_FOUND：

用户不存在

1.3getResult（操作的返回结果）

publicfinaljava.lang.StringgetResult（）

功能：

操作的返回结果（只对有返回结果的操作才有意义）

返回值类型：

请参考各个API函数调用的说明

1.4getResultEx（返回操作的返回结果）

publicfinalObjectgetResultEx（）

功能：

返回操作的返回结果.和getResult不同的是,此方法可以返回其它数据类型.

返回值类型：

操作的返回结果.

1.5getErrorInfo（描述操作失败原因）

publicfinaljava.lang.StringgetErrorInfo（）

功能：

操作失败时对操作失败原因的描述字符串

返回值类型：

失败原因的描述字符串

1.6toString（返回操作结果的字符串表示）

publicfinalStringtoString（）

功能：

返回操作结果的字符串表示

返回值类型：

操作结果的字符串表示

2API函数的使用步骤

配置访问CoremailAPI服务器的ip

用户通过调用API接口函数进行二次开发前，请用户预先配置好要访问API机器的ip。

如果不设置访问机器的ip，用户将不允许进行API访问。

配置方法如下：

1.登录系统管理界面，点击全局设定功能

2.选择配置管理中的“API”如下图，在“IP设置”一栏中设置好要访问机器的ip

使用Coremail4.0的API库：

1.将所提供的APIClient.jar添加到的运行环境中（classpath）

2.参考实例程序：

APIDemo.java

程序过程：

1．实例化.Socket类，建立网络连接

2．利用1建立的Socket实例，使用APIContext.getClient（.Socketsocket）提供的工厂方法，获取客户端的IClient的对象实例

3．用IClient的createUser，changeAttrs，setTimeOut等成员函数执行具体任务，返回APIContext类型的对象，通过APIContext.getRetCode以及APIContext.getResult方法获取返回结果。

4．用IClient的实例的close方法关闭连接

APIjava接口调用方法：

apiSubmit（StringencodedCommand）

其中cmd=x&.....&attrs=URL编码过的attrs属性。

attrs属性，为输入批量属性。

范例：

（可参考APIDemo.java）

Socketsocket=newSocket（"127.0.0.1",6195）;

IClientclient=APIContext.getClient（socket）;

try{

APIContextret=client.createUser（"1","a","foo",

"domain_name=&cos_id=1&user_status=0"a_delta=0"）;

if（ret.getRetCode（）==APIContext.RC_NORMAL）{

System.out.println（"Usercreated:

foo@"）;

}else{

System.out.println（"Usercreatefailed,code="+ret.getRetCode（）

+",msg="+ret.getErrorInfo（））;

}

}finally{

client.close（）;

}

3Coremail4.0API具体功能应用

3.1登录

3.1.1用户登录

cmd命令号：

5

方法名称：

userLogin

功能：

用户登录,使用所有缺省参数.

入口参数：

user_at_domain用户邮件地址:

user_id@domain_name

返回值类型：

操作成功时，返回到APIContext:

result的是用户的sessionID

抛出异常类型：

java.io.IOException

cmd命令号：

5

方法名称：

userLoginEx

功能：

用户登录,使用附加参数，并返回额外的信息

入口参数：

user_at_domain-用户邮件地址:

user_id@domain_name

attrs-操作属性,属性值中如果有特殊字符必须用url的方式编码,如等于号"="编码为"%3D"。

详细说明：

操作成功时，返回到APIContext:

result为encode的用户属性字符串:

"sid=[用户的sessionid]&webname=[web主机前缀]";web主机前缀包含协议,机器IP,端口部分,并且结尾不包含'/'符号

∙例如:

∙又如:

:

8080

支持的操作属性,见下表:

属性名

属性含义

type

登录类型:

例如"WEB"/"API"（默认）这样的字符串（CoremailXTU3后才支持）所有支持的类型包括:

"WEB"/"POP3"/"IMAP"/"SMTP"/"API"

remote_ip

登录用户的IP

ipcheck

仅为"1"时表示需要检查浏览器的IP

cookiecheck

检查浏览器的cookie值

language

登录的语言,和配置有关,为"0"/"1"等数字

style

登录的风格,和配置有关,为"0"/"1"等数字

返回值类型：

APIContext的retCode是操作结果，0表示操作成功，其他值代表操作失败，请参考返回信息表。

抛出异常类型：

java.io.IOException

3.1.2检查用户是否存在

cmd命令号：

4

方法名称：

userExist

功能：

检验用户是否存在

入口参数：

user_at_domain用户邮件地址:

user_id@domain_name

返回值类型：

APIContext的retCode是操作结果，0表示操作成功，其他值代表操作失败，请参考返回信息表。

抛出异常类型：

java.io.IOException

3.1.3验证用户密码

cmd命令号：

12

方法名称：

authenticate

功能：

验证用户密码.

入口参数：

user_at_domain用户邮件地址:

user_id@domain_name

password用户密码

返回值类型：

APIContext的retCode是验证结果，0表示验证通过，35表示验证失败，其它返回值参照说明。

关键错误代码包括：

APIContext.RC_USER_NOT_FOUND:

用户不存在

APIContext.RC_PASSWORD_ERR:

密码验证失败

抛出异常类型：

java.io.IOException

3.1.4检查用户的session，返回用户信息

cmd命令号：

9

方法名称：

sesTimeOut

功能：

检查用户session，并返回用户的信息.

入口参数：

ses_id用户sessionID

返回值类型：

操作成功时，返回到APIContext:

result的格式为：

uid=...@...&domain_id=...&org_id=...，而uid为user@domain的格式，即用户的邮件地址

关键错误代码包括：

APIContext.RC_SESID_NOT_FOUND:

sessionID不存在或已经过时

APIContext.RC_SES_ERROR或其它值:

其它的session错误

抛出异常类型：

java.io.IOException

3.1.5检查用户的session，并刷新访问时间

cmd命令号：

10

方法名称：

sesRefresh

功能：

检查用户session，并刷新访问时间.

入口参数：

ses_id用户sessionid

返回值类型：

操作成功时，除了返回值没有其它信息，表示传入的是合法的session，并且已经刷新.

关键错误代码:

APIContext.RC_SESID_NOT_FOUND:

sessionid不存在或已经过时

APIContext.RC_SES_ERROR或其它值:

其它的session错误

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.1.6获取用户session中的变量

cmd命令号：

8

方法名称：

getSesssionVar

功能：

获取用户session中的变量.

入口参数：

ses_id用户sessionid

ses_key要获取的变量名

返回值类型：

操作成功时，变量的值直接返回到APIContext:

result关键错误代码:

关键错误代码:

APIContext.RC_SESID_NOT_FOUND:

sessionid不存在或已经过时

APIContext.RC_SES_ERROR或其它值:

其它的session错误

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.1.7用户退出

cmd命令号：

6

方法名称：

userLogout

功能：

结束用户session

入口参数：

ses_id用户sessionID

返回值类型：

APIContext的retCode是操作结果，0表示操作成功，其他值代表操作失败，请参考返回信息表。

抛出异常类型：

java.io.IOException

3.2组织维护

3.2.1创建组织

cmd命令号：

22

方法名称：

addOrg

功能：

创建组织

入口参数：

org_id-String组织ID

attrs-String组织属性串attrs的格式,&号分隔的key=value,例如:

cos_id=1&number_of_classes=100...可用属性（可选）如下表:

属性名

属性含义

org_name

组织名称,如果不提供则org_name=OrgID

domain_name

组织的许可域名。

如果是不存在的域名会先自动创建域名

res_grp_id

资源组ID,如果不填则使用programs/RmiServer/APIDefaultRes下的配置值

cos_id

创建组织时可指定一个COSID,并分配数量。

缺省取programs/RmiServer/APIDefaultCos下的配置值（配置值用cos_name指定COS）

num_of_classes

指定的COSID类型用户数限制，

org_assignable_quota

可分配容量

org_status

组织状态（0正常1暂停2锁定）

org_expiry_date

过期日期。

NULL或者空表示不过期。

格式为:

yyyy-mm-dd

org_address

地址

org_phone_number

电话

org_contact

联系人

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.2.2获取组织属性

cmd命令号：

24

方法名称：

getOrgInfo

功能：

获取组织属性

入口参数：

org_id-String组织ID

attrs-String组织属性串可获取属性（可选）如下表:

属性名

属性含义

org_name

组织名称

domain_name

组织的许可域名列表,以逗号","分隔

res_grp_id

资源组ID

org_assignable_quota

可分配容量

org_status

组织状态（0正常1暂停2锁定）

org_expiry_date

过期日期。

NULL或者空表示不过期。

格式为:

yyyy-mm-dd

org_address

地址

org_phone_number

电话

org_contact

联系人

not_used_quota

此ORG还剩余的容量，单位M

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.2.3修改组织属性

cmd命令号：

23

方法名称：

alterOrg

功能：

修改组织属性

入口参数：

org_id-String组织ID

attrs-String组织属性串可修改属性

属性名

属性含义

org_name

组织名称

org_assignable_quota

可分配容量

org_status

组织状态（0正常1暂停2锁定）

org_expiry_date

过期日期。

NULL或者空表示不过期。

格式为:

yyyy-mm-dd

org_address

地址

org_phone_number

电话

org_contact

联系人

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.2.4组织域名分配（添加/删除）

cmd命令号：

26

方法名称：

addOrgDomain

功能：

添加组织的许可域名

入口参数：

org_id-组织ID

domain_name-要分配的许可域名

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

cmd命令号：

27

方法名称：

delOrgDomain

功能：

删除组织的许可域名

入口参数：

org_id-组织ID

domain_name-要取消的许可域名

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.2.5组织COS分配（添加/修改/删除）

cmd命令号：

28

方法名称：

addOrgCos

功能：

为指定组织添加一种COS（服务等级）.

入口参数：

org_id-组织ID

cos_name-服务等级名称

num_of_classes-该服务等级的用户数

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

cmd命令号：

29

方法名称：

alterOrgCos

功能：

修改指定组织一种COS（服务等级）.

入口参数：

org_id-组织ID

cos_name-服务等级名称

num_of_classes-该服务等级的用户数

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

cmd命令号：

30

方法名称：

delOrgCos

功能：

删除指定组织一种COS（服务等级）.

入口参数：

org_id-组织ID

cos_name-服务等级名称

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.2.6根据COS获取用户列表

cmd命令号：

42

方法名称：

getOrgCosUser

功能：

列出指定组织某服务等级（COS）下的所有用户名列表.

入口参数：

org_id-组织ID

cos_id-服务等级ID

返回值类型：

用户名不包含“@domain"信息

操作成功时，返回到APIContext:

result为要获取的用户列表，","分隔,如user1,user2,user3

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.2.7获取站点所有组织标识列表

cmd命令号：

43

方法名称：

getOrgList

功能：

列出所有组织ID.

返回值类型：

操作成功时，返回到APIContext:

result为要获取的用户列表，","分隔,如user1,user2,user3

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.3部门维护

3.3.1创建部门

cmd命令号：

304

方法名称：

addUnit

功能：

创建部门。

如果不设置parent_org_unit_id属性则表示创建直属部门。

入口参数：

org_id-组织ID

org_unit_id-部门ID

attrs-要设置的部门属性,parent_org_unit_id设置上级部门的ID,org_unit_name设置部门名称

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.3.2删除部门

cmd命令号：

305

方法名称：

delUnit

功能：

删除组织部门。

入口参数：

org_id-组织ID

org_unit_id-部门ID

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.3.3获取部门属性

cmd命令号：

306

方法名称：

getUnitAttrs

功能：

获取部门信息。

入口参数：

org_id-组织ID

org_unit_id-部门ID

attrs-要获取的部门属性,parent_org_unit_id获取上级部门的ID,org_unit_name获取部门名称

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.3.4设置部门属性

cmd命令号：

307

方法名称：

setUnitAttrs

功能：

设置部门属性。

如果设置parent_org_unit_id属性则相当于移动部门,如果想移动到根成为直属部门,可以使用"parent_org_unit_id="作为attrs参数。

例如：

要想部门在排序中排在前面，则须设置"org_unit_list_rank="，排序以数字大的优先，即数字越大，排位越靠前。

入口参数：

org_id-组织ID

org_unit_id-部门ID

attrs-要设置的部门属性,parent_org_unit_id设置上级部门的ID,org_unit_name设置部门名称

返回值类型：

操作结果,见附录的说明

抛出异常类型：

java.io.IOException

3.4用户维护

3.4.1创建用户

cmd命令号：

0

方法名称：

createUser

功能：

创建用户

入口参数：

providerId用户的providerid,必须为存在的provider，属性password如果不设置将使用缺省值为随机密码

org_id用户的组织id,必须为存在的组织

user_id用户id,满足rfc规定的用户名

attrs用户的其它属性，如：

"domain_name