FIBOS IDL文件初探

[luoyhang003]

初探 IDL

在前不久，FIBOS 向社区开源了 IDL 文件，你可以在 GitHub 里查看它们。那么 IDL 对 FIBOS 来说意味着什么，我们开发者使用 IDL 又能做什么呢？本文将带你一探究竟。

所谓 IDL 就是接口描述语言(Interface description language)，指描述某一种变成语言的接口的文件。一般用于对外声明接口起到文档的作用，同时可以用来编译成某种语言的代码。

更具象的来谈，我们知道 FIBOS 是基于 Fibjs + EOS 的，所以在 FIBOS 体系中，IDL 文件描述了 Fibjs 的对象和模块的结构，用它可以生成头文件和对应的文档。然后 FIBOS 将其注册到自己的沙箱中，从而可以在 JavaScript 中调用 FIBOS 提供的模块和方法。今天仅仅介绍 IDL 文件的构成和使用方法。

解析 IDL

在阅读 IDL 之前，我们首先需要了解一下在 FIBOS 中 IDL 支持哪些数据类型。IDL 支持两种类型：

• 内置的字典集。在生成头文件的过程中，生成工具可以将 IDL 中的类型转换成 C++中头文件中对应的类型，它们是：

var typeMap = {
    "Integer": "int32_t",
    "Long": "int64_t",
    "Number": "double",
    "Boolean": "bool",
    "String": "exlib::string",
    "Date": "date_t",
    "Object": "v8::Local<v8::Object>",
    "Iterator": "v8::Local<v8::Object>",
    "Array": "v8::Local<v8::Array>",
    "TypedArray": "v8::Local<v8::TypedArray>",
    "ArrayBuffer": "v8::Local<v8::ArrayBuffer>",
    "ArrayBufferView": "v8::Local<v8::ArrayBufferView>",
    "Function": "v8::Local<v8::Function>",
    "Value": "v8::Local<v8::Value>",
    "Variant": "Variant",
    "NObject": "obj_ptr<NObject>",
    "NArray": "obj_ptr<NArray>",
    "...": "OptArgs"
};

• 自己定义的数据类型。IDL 在生成的头文件中会自动引入xxxx_base的文件，并使用其中的方法。

小试牛刀

我们以一个简单的例子开始。下面我定义了一个name的 IDL 文件，它提供两个方法。

• check方法，其参数是一个String，默认的字典类型，用来判断所传入的字符串是否等于“FIBOS”，返回值是boolean类型
• sha256方法，其参数是我们自己定义Buffer类型，用来创建一个 SHA256 信息摘要运算对象。

文件实例如下：

/*! @brief 
 name 对象
 */

module name {
    /*! @brief 检测字符串是否为 FIBOS
     @param String text 所需检验的字符
    */
    static Boolean check(String text);

    /*! @brief 创建一个 SHA256 信息摘要运算对象
     @param data 创建同时更新的二进制数据
     */
    static String sha256(Buffer data);
};

你可以在 tools 目录下执行fibos idlc.js，该文件会读取 idl 目录下的所有 idl 文件并进行解析，生成对应的头文件。这些生成的头文件会存放在在 fibos/include/ifs 目录下，执行后生成文件如下：

/***************************************************************************
 *                                                                         *
 *   This file was automatically generated using idlc.js                   *
 *   PLEASE DO NOT EDIT!!!!                                                *
 *                                                                         *
 ***************************************************************************/

#ifndef _name_base_H_
#define _name_base_H_

#include "../object.h"

namespace fibjs {

class Buffer_base;

class name_base : public object_base {
    DECLARE_CLASS(name_base);

public:
    // name_base
    static result_t check(exlib::string text, bool& retVal);
    static result_t sha256(Buffer_base* data, exlib::string& retVal);

public:
    static void s__new(const v8::FunctionCallbackInfo<v8::Value>& args)
    {
        CONSTRUCT_INIT();

        Isolate* isolate = Isolate::current();

        isolate->m_isolate->ThrowException(
            isolate->NewString("not a constructor"));
    }

public:
    static void s_check(const v8::FunctionCallbackInfo<v8::Value>& args);
    static void s_sha256(const v8::FunctionCallbackInfo<v8::Value>& args);
};
}

#include "ifs/Buffer.h"

namespace fibjs {
inline ClassInfo& name_base::class_info()
{
    static ClassData::ClassMethod s_method[] = {
        { "check", s_check, true },
        { "sha256", s_sha256, true }
    };

    static ClassData s_cd = {
        "name", true, s__new, NULL,
        ARRAYSIZE(s_method), s_method, 0, NULL, 0, NULL, 0, NULL, NULL, NULL,
        &object_base::class_info()
    };

    static ClassInfo s_ci(s_cd);
    return s_ci;
}

inline void name_base::s_check(const v8::FunctionCallbackInfo<v8::Value>& args)
{
    bool vr;

    METHOD_NAME("name.check");
    METHOD_ENTER();

    METHOD_OVER(1, 1);

    ARG(exlib::string, 0);

    hr = check(v0, vr);

    METHOD_RETURN();
}

inline void name_base::s_sha256(const v8::FunctionCallbackInfo<v8::Value>& args)
{
    exlib::string vr;

    METHOD_NAME("name.sha256");
    METHOD_ENTER();

    METHOD_OVER(1, 1);

    ARG(obj_ptr<Buffer_base>, 0);

    hr = sha256(v0, vr);

    METHOD_RETURN();
}
}

#endif

可以看到，通过工具我们将 IDL 快速转化为了.h文件，其中类型的转化也与我们预期的相符，即内置类型进行相应转化，非内置类型引用对应的 class 文件。

FIBOS 官方提供了大量原生的 JavaScript 的模块和方法，你可以在 dev.fo 了解它们。通过以上的讲解你应该可以配合已经开源的 IDL 文件轻松的理解 FIBOS 中各个模块和方法的定义了。

加入我们

FIBOS 开源工作正在持续进行。您可以在 GitHub 关注我们，与我们一起完善 FIBOS。

欢迎您来为 FIBOS 贡献更多的力量。

---

Written by @PinelliaC