Page tree
Skip to end of metadata
Go to start of metadata

Supported Types

JSAPIAuto type support derives from the types supported by FB::variant.  When JSAPIAuto converts an argument to the type your JSAPI method or property expects, it does so using FB::variant::convert_cast<type>. Understanding this will help you get the most out of the incredibly powerful type system that FireBreath supports.

Arithmetic Types

FireBreath supports all arithmetic types and will automatically convert between them.  This includes, but may not be limited to:

  • (signed/unsigned) int
  • (signed/unsigned) long
  • (signed/unsigned) short
  • (signed/unsigned) char
  • float
  • double
  • size_t

Boolean Types

FireBreath supports the bool type and will convert common string representations such as "1", "t", "true", "yes", or "y" to true, anything else to false.

String types

FireBreath supports both std::string and std::wstring and will automatically convert between them -- note that std::string representations are always UTF8 encoded.

char* and wchar_t*

As a return type only (or assigning to a FB::variant) you can use char* or wchar_t*, but these will get converted internally to std::string and std::wstring respectively.

Binary Data

If you need to pass binary data to the page we recommend that you either convert it to a string (hex, base64, etc) or perhaps wrap it in a Javascript Array (such as a std::vector<unsigned char>). Note that passing such data as a Javascript array won't be terribly efficient, but the plugin interfaces don't really allow for binary data.  All strings are assumed by the browser to be UTF8, so simply returning a char* is likely to produce unexpected results.

Container types

FireBreath supports all STL container (and 100% compatible) types. Associative types can be used as parameters to JSAPI methods and javascript objects will be automatically converted into, whereas non-associative types can hold data from JavaScript arrays.

Please note that return values utilizing containers must be one of the following two types:

  • FB::VariantList (typedef for std::vector<FB::variant>)
  • FB::VariantMap (typedef for std::map<std::string, FB::variant>)

Note that this is not a limitation! You can assign any valid FB type (any type on this page) to a FB::variant, so a method returning a FB::VariantList could return a list of FB::VariantMap objects each containing FB::JSAPIPtr objects, etc. Since JavaScript is loosely/dynamically typed it will be completely useable when it gets back to the page.

JavaScript Objects

Javascript objects can be used with the FB::JSObjectPtr type. Examples of JavaScript objects that you may want to use include:

  • Javascript objects (with methods and/or value members)
  • Javascript Arrays (that you plan to modify; otherwise you can use a container type)
  • Javascript methods for callback

Note that when using these objects from another thread, InvokeAsync or SetPropertyAsync should be used whenever appropriate instead of the synchronous version to avoid the performance hit of making a cross-thread synchronous call.

JSAPI Objects

One of the most powerful features of FireBreath is the ability for one JSAPI object to return another, thus giving you a rich multi-layer object interface.  JSAPI objects can be passed in using FB::JSAPIPtr and returned using the same wrapper.

Starting in FireBreath 1.4: Any JSAPI-derived type wrapped in a boost::shared_ptr can be used as a return type or as a parameter type. An example use-case for a JSAPI-derived type as a parameter would be if you need to pass in an object that was previously obtained from your plugin.

Optional Types

Starting in FireBreath 1.4: Any valid type can be wrapped in a boost::optional type to create an optional version of that type. If optional types are at the end of the argument list in a method they can be left off when calling the function.

boost::variant Types

Starting in FireBreath 1.4: Any of these types can be used to create a boost::variant; when used as a parameter type the input value will be passed in as either the matching type or the first successful conversion.

boost::tribool Type

Starting in FireBreath 1.4: boost::tribool is supported allowing true, false, and indeterminate.  When converting to this type null or undefined will map to indeterminate.

Enumeration Types

Starting in FireBreath 1.4: Enum types can be used as a return value, but they will simply be converted to an integral type before being returned to the browser

  • No labels

1 Comment

  1. Unknown User (pnd1305)

    JSAPIAuto类型源自于 FB::variant.  当JSAPIAuto帮助对象转换输入、返回的参数数据为 JSAPI对象可用的参数数据时,就是用 FB::variant::convert_cast<type>进行转换的. 理解这点才能最大限度发挥FB的作用。

    算术型-FireBreath 支持所有算术型参数并自动换算,包括如下并不限于

    逻辑型 FireBreath 支持。并自动将字符串 "1", "t", "true", "yes", or "y" 视为 true, 其它字符视为false.

    字符型-FireBreath 支持 std::string and std::wstring 和自动转换,注 std::string 总是 UTF8 .

    char* and wchar_t*可作为返回数据类型,但这会内部转换成std::string 和std::wstring

    位数据

    如果需要将位数据返回网页,建议转换成字符串 (hex, base64, etc) 或封装成一个JS数组 ( std::vector<unsigned char>). 注这是低效做法,插件对象是不真正支持位数的. 浏览器视同所有的字符串为 UTF8, 所以简单的返回  char* 有可能出错.

    容器型

    FireBreath 支持 STL 容器型 (100%). 可作为JSAPI对象的方法返回并JS对象能自动转换成可处理的JS数据类型.

    注仅支持:

    • FB::VariantList (typedef for std::vector<FB::variant>)
    • FB::VariantMap (typedef for std::map<std::string, FB::variant>)

    实际应用上无限支持!因任何类型都可转换成 FB::variant,所以一个返回 FB::VariantList就可以返回一列 list of FB::VariantMap objects 。JS对象也完成可用.

    JS对象用 FB::JSObjectPtr 数据类型. 例如范围:

    • Js对象 (有方法,数据)
    • Js数据(有修改必要的; 否则可容器型)
    • 用于callback的JS函数

    注如要JS对象可被其它线程引用时,则需要 InvokeAsync or SetPropertyAsyncl.

    JSAPI 对象

    最强大的特性,JSAPI对象可用另一JSAPI对象,实现多层次的接口交互.  JSAPI 对象传递是用 FB::JSAPIPtr.

    Optional Types可选型

    Starting in FireBreath 1.4: 任何有效类型数据可组成 boost::optional型,变成可选版本.如果可选型是在参数数组末时可以不用,当该函数应用时.

    boost::variant Types 与FB::Variant 有何不同?

    Starting in FireBreath 1.4: Any of these types can be used to create a boost::variant; when used as a parameter type the input value will be passed in as either the matching type or the first successful conversion.

    boost::tribool Type 可以值是true, false 和不确定的(null ,undefined),

    Enumeration Types 枚举型,在返回浏览器前会被转换成完整的类型?