鸿蒙HarmonyOS系统应用开发|接口描述语言构成

数据类型

HarmonyOS IDL支持的数据类型可分为：基本数据类型、自定义类型、声明的Sequenceable数据类型、声明的接口类型、数组类型以及容器类型。

• 基本数据类型

HarmonyOS IDL基本数据类型与Java数据类型、C/C++数据类型的对应关系如下表所示：

HarmonyOS IDL基本数据类型	Java数据类型	C++数据类型	C数据类型	数据长度(bytes)
void	void	void	void	NA
boolean	boolean	bool	bool	1
byte	byte	int8_t	int8_t	1
short	short	int16_t	int16_t	2
int	int	int32_t	int32_t	4
long	long	int64_t	int64_t	8
float	float	float	float	4
double	double	double	double	8
String	String	std::string	cstring	NA
unsigned char	不支持	uint8_t	uint8_t	1
unsigned short	不支持	uint16_t	uint16_t	2
unsigned int	不支持	uint32_t	uint32_t	4
unsigned long	不支持	uint64_t	uint64_t	8

• 自定义类型

  自定义类型是指使用关键字struct、union、enum定义的结构体类型、联合体类型、枚举类型，以及这些类型组合嵌套定义的类型。自定义类型文件MyTypes.idl示例如下：

package ohos.module;
 
struct Example1 {
    String member1;
    unsigned int member2;
};
union Example2 {
    String member1;
    unsigned int member2;
};
enum Example3 : int {
    RED,
    BLUE,
    GREEN,
};
struct Example1_2_3 {
    struct Example1;
    union Example2;
    enum Example3;
};

在定义枚举类型时，需要指定枚举类型的基本数据类型，可以使用byte、short、int、long、unsigned char、unsigned short、unsigned int、unsigned long。如果未指定，则默认基础类型为int类型。

一个模块在定义HarmonyOS IDL接口时使用的自定义类型应该定义在一个独立的文件中，不要分散到每个接口定义的文件中。自定义类型所在文件的名称可以根据实际情况进行定义，在接口定义文件中需要导入自定义类型文件，例如：MyInterface.idl接口使用了MyTypes.idl中定义的自定义类型，代码示例如下：

package ohos.module;
 
import ohos.module.MyTypes;
 
interface ohos.module.MyInterface {
……
}

HarmonyOS IDL自定义数据类型与Java数据类型、C/C++数据类型的对应关系如下表所示：

自定义数据类型	Java数据类型	C++数据类型	C数据类型
struct	不支持	struct	struct
union	不支持	union	union
enum	不支持	enum	enum

• Sequenceable数据类型

  Sequenceable数据类型是指用“Sequenceable”关键字声明的非基本数据类型，表明该数据类型可以通过Parcel进行跨进程（或跨设备）传递。声明放在文件的头部，形式为 “sequenceable namespace.typename;”，namespace是该类型所属的命名空间，内部采用“.”连接不同层级的命名空间，typename是类型名。例如：“sequenceable com.huawei.samples.ApplicationInfo;”表示ApplicationInfo类型可以通过Parcel进行跨进程传递。

  Sequenceable数据类型并不在HarmonyOS IDL文件中定义，而是定义在C++文件或Java文件中，C语言文件不支持。因此，HarmonyOS IDL工具将根据声明在生成的C++代码文件中加入“#include "com/huawei/samples/ApplicationInfo.h"”语句，在生成的Java代码文件中加入“import com.huawei.samples.ApplicationInfo;”语句。

  HarmonyOS IDL Sequenceable数据类型与Java数据类型、C/C++数据类型的对应关系如下表所示：

  HarmonyOS IDL数据类型	Java数据类型	C++数据类型	C数据类型
  Sequenceable	import namespace.typename; 例如：import com.huawei.samples.ApplicationInfo;	#include namespace/typename.h" using namespace::typename 例如：#include com/huawei/samples/ApplicationInfo.h" using com::huawei::samples::ApplicationInfo	不支持

• 接口类型

  接口类型是指HarmonyOS IDL文件中定义的接口。对于当前IDL文件中定义的接口，可以直接使用它作为方法参数类型或返回值类型。而在其它HarmonyOS IDL文件中定义的接口，则需要在文件的头部进行前置声明。声明的形式为“interface namespace.interfacename;”，namespace是该接口所属的命名空间，内部采用“.”连接不同层级的命名空间，interfacename是接口名。例如：“interface com.huawei.samples.IApplication;”声明了在其他HarmonyOS IDL文件定义的IApplication接口，该接口可以作为当前定义中方法的参数类型或返回值类型使用。

  HarmonyOS IDL工具将根据该声明在生成的C++代码文件中加入“#include "com/huawei/samples/IApplication.h"”语句，在生成的Java代码文件中加入“import com.huawei.samples.IApplication;”语句。IBroker也是接口类型的一种，使用它无需前置声明。

  HarmonyOS IDL接口数据类型与Java数据类型、C/C++数据类型的对应关系如下表所示：

  HarmonyOS IDL数据类型	Java数据类型	C++数据类型	C数据类型
  Interface	import namespace.interfacename; 例如：import com.huawei.samples.IApplication;	#include namespace/interfacename.h" using namespace::interfacename; 例如：#include com/huawei/samples/IApplication.h" using com::huawei::samples::IApplication;	不支持

• 数组类型

  数组类型用“T[]”表示，T可以是基本数据类型、自定义类型、Sequenceable数据类型、接口类型和数组类型。

  在C++代码中，数组类型生成为std::vector，在Java代码中，数组类型生成为T[]。

  HarmonyOS IDL数组数据类型与Java数据类型、C/C++数据类型的对应关系如下表所示：

  HarmonyOS IDL数据类型	Java数据类型	C++数据类型	C数据类型
  T[]	T[]	std::vector	T*,int size

• 容器类型

  当前支持两种容器：List和Map。List容器用法为“List”， Map容器用法为“Map”，T、KT和VT可以为基本数据类型、自定义类型、Sequenceable类型、接口类型、数组类型或容器类型。

  在C++代码中，List容器类型生成为std::list，Map容器类型生成为std::map。在Java代码中，List容器类型生成为ArrayList，Map容器类型生成为HashMap。

  HarmonyOS IDL容器数据类型与Java数据类型、C/C++数据类型的对应关系如下表所示：

  HarmonyOS IDL数据类型	Java数据类型	C++数据类型	C数据类型
  List	List	std::list或std::vector	T*,int size
  Map	HashMap	std::map或std::unordered map	不支持

接口定义

一个HarmonyOS IDL文件只能定义一个接口类，接口定义的形式使用BNF范式描述，示例如下：

<*interface_attributes_declaration*> ? interface <*interface_name_with_namespace*> { <*method_declaration*> ? }

<*interface_attributes_declaration*>是接口属性声明，当前支持oneway、callback、full、lite属性：

• oneway：表示该接口中的方法都是单向方法，即调用方法后不用等待该方法执行即可返回。该属性为可选项，如果无声明，则默认为同步调用方法。
• callback：表示该接口为callback接口，即从下层实现中回调到上层服务中。
• full、lite：表示该接口在重量级部署或轻量级部署中使用。如果无声明，则默认为重量级、轻量级部署中都会使用。

<*interface_name_with_namespace*>是接口名声明，接口名需包含完整的命名空间，且必须包含方法声明，不允许出现空接口。接口示例：

[oneway] interface ohos.app.IAbilityManager {
    ……
};

<*method_declaration*>是方法声明，形式为：

<*method_attributes_declaration*> ? <*result type*> <*method declarator*>

<*method_attributes_declaration*>是方法属性声明。当前支持oneway 、full、lite属性：

• oneway：表示该方法是单向方法，即调用方法后不用等待该方法执行即可返回。
• full、lite：表示该方法在重量级部署或轻量级部署中使用。如果无声明，则默认为重量级、轻量级部署中都会使用。

<*result type*>是返回类型，<*method declarator*>是方法名和各个参数声明，参数声明的形式为：

\[ <*formal_parameter_attribute*> \] <*type*> <*identifier*>

<*formal_parameter_attribute*>的值为“in”、“out”或“inout”，分别表示该参数是输入参数、输出参数或输入输出参数。oneway方法不允许有输出参数（包含输入输出参数）和返回值。

方法示例：

void SetBundles([in] Map bundleInfos,  [in, out] int number);
[oneway] void Dump([in] ParcelableFileDescriptor fd,  [in] long flags);

在HarmonyOS IDL接口描述文件中可以使用的关键字如下表所示：

HarmonyOS IDL keywords	详细说明
void、boolean、byte、short、int、long、float、double	基本数据类型，void类型、bool型、整型、浮点型等
unsigned	在定义无符号类型时使用，如unsigned char、unsigned short、unsigned int、unsigned long
String	定义字符串时使用
struct	结构体类型
union	联合体类型
enum	枚举类型
T[]	T可以是基本数据类型、自定义类型、Sequenceable数据类型、接口类型和数组类型
List<>	容器类型List，T为基本数据类型、自定义类型、Sequenceable类型、接口类型、数组类型或容器类型
Map<>	容器类型Map： KT和VT为基本数据类型、自定义类型、Sequenceable类型、接口类型、数组类型或容器类型
Sequenceable	该类型并不在idl文件中定义，而是定义在C++文件或Java文件中
package	包名
import	引用一个包、一个自定义类型文件、一个接口(限定HarmonyOS IDL文件生成的接口类)
extends	接口继承
interface	接口类型
[oneway]	表示单向接口或方法 oneway方法不允许有输出参数（包含输入输出参数）和返回值
[in]	输入参数
[out]	输出参数
[inout]	输入输出参数
[callback]	标识一个接口为回调接口定义（明示工具如何生成service、client代码）
[full]	仅在HarmonyOS重量级部署中使用的参数、接口、方法
[lite]	仅在HarmonyOS轻量级部署中使用的参数、接口、方法

注释说明

HarmonyOS IDL文件中的注释采用与C/C++相同的方式，可以采用//或者/* … */的方式进行注释说明。

 

         本网站中的部分文档和示例代码来自第三方，您可通过NOTICE查看详情。