Embedding SpiderMonkey

サポートするJavaScriptのバージョン

JSエンジンはJS 1.0から1.4をサポートします。JS 1.3以上はECMAScript-262規格に従います。より基本的には、JSエンジンはJS構文と関数をふくむスクリプトを、パースし、コンパイルして実行します。エンジンはスクリプトの実行に必要な、データやオブジェクトのために、メモリを取得し、クリーンナップ（ガベレージコレクション＝必要でなくなったデータやオブジェクトをメモリを解放）します。The JS engine supports JS 1.0 through JS 1.4. JS 1.3 and greater conform to the ECMAScript-262 specification. At its simplest, the JS engine parses, compiles, and executes scripts containing JS statements and functions. The engine handles memory allocation for the JS data types and objects needed to execute scripts, and it cleans up -- garbage collects -- the data types and objects in memory that it no longer needs.

How Do You Use the Engine?

一般に、JSエンジンは共用ライブラリとしてビルドされます。 例えば、WindowsとWindows NTではDLL、Unixでは共有ライブラリとして。 あなたは、アプリケーションにそれにリンクして、JSエンジンアプリケーションプログラミングインタフェース(API)呼び出します。 JSエンジンのAPIは以下の広いカテゴリにわたる機能を提供します:Generally, you build the JS engine as a shared resource. For example, the engine is a DLL on Windows and Windows NT, and a shared library on Unix. Then you link your application to it, and embed JS engine application programming interface (API) calls in your application. The JS engine's API provides functions that fall into the following broad categories:

• データ型操作Data Type Manipulation
• ランタイム・コントロールRun Time Control
• クラスとオブジェクトの作成と管理Class and Object Creation and Maintenance
• 関数とスクリプトの実行Function and Script Execution
• 文字列の操作String Handling
• エラー・ハンドリングError Handling
• セキュリティーコントロールSecurity Control
• デバッグ機能Debugging Support

これらのカテゴリの内、ランタイム・コントロールやデータ型操作はあらゆるアプリケーションで必要です。例えば、すべてのJS関数を呼び出す前に、JS_NewRuntimeを実行して、JSエンジンを作成・初期化しなければなりません。対して、セキュリティコントロールなどは必要であれば使用することができる機能です。You will use some of these functional categories, such as run time control and data type manipulation, in every application where you embed JS calls. For example, before you can make any other JS calls, you must create and initialize the JS engine with a call to the <code>JS_NewRuntime</code> function. Other functional catergories, such as security control, provide optional features that you can use as you need them in your applications.

How Does the Engine Relate to Applications?

JSエンジンはシステムの共用リソースです。 アプリケーションは、APIを呼び出すことで、JSエンジンに要求を伝えることができます。 エンジンは、順番に要求を処理し、値か状態情報を返します。Conceptually, the JS engine is a shared resource on your system. By embedding engine API calls in your applications you can pass requests to the JS engine for processing. The engine, in turn, processes your requests, and returns values or status information back to your application. Figure 1.1 illustrates this general relationship:

図 1.1

例えば、JavaScriptを利用して、ユーザを認証し、ユーザのアクセス権を設定するアプリケーションがあるとします。まず最初に、アプリケーションは、ユーザの名前、ID、アクセス権、など含んでいるカスタムJSオブジェクトを作成することでしょう。For example, suppose you are using the JS engine to automate your application using JS scripts, and suppose that one script your application runs authenticates a user and sets a user's access rights to the application. First, your application might create a custom JS object that represents a user, including slots for the user's name, ID, access rights, and a potential list of functions that the user has permission to use in the application.

この場合、アプリケーションはカスタム・オブジェクトを作成するために、JS_NewObjectを呼び出します。<!-In this case, your application's first request to the JS engine might be a call to JS_NewObject to create the custom object.-->JSエンジンは、オブジェクトを作成したら、そのポインタをアプリケーションに返します。When the JS engine creates the object, it returns a pointer to your application. 次に、アプリケーションは「オブジェクトを使用するスクリプト」を実行するために、JSエンジンを呼び出します。Your application can then call the JS engine again to execute scripts that use the object.例えばあなたのアプリケーションは、ユーザ・オブジェクトを作成した後、スクリプトをコンパイルして実行するために、スクリプト・コードをJS_EvaluateScriptに渡すでしょう。For example, after creating the user object, your application might immediately pass a script to <code>JS_EvaluateScript</code> for immediate compiling and executing. そのスクリプトは、ユーザの情報を確認し、他の機能を有効にするための設定をするものです。That script might get and validate a user's information, and then establish the user's access rights to other application features.

実際には、アプリケーションとJSエンジンとの実際の図1.1で示されるよりいくらか複雑です。まずプラットホーム用のJSエンジンがビルドしないといけません。そして、JSエンジンを利用するコードではjsapi.hをincludeします。そして、アプリケーションは最初にJSランタイムを初期化します。In truth, the actual relationship between your application and the JS engine is somewhat more complex than shown in Figure 1.1. For example, it assumes that you have already built the JS engine for your platform. It assumes that your application code includes <code>jsapi.h</code>, and it assumes that the first call your application makes to the engine initializes the JS run time.

JSエンジンは初期化要求を受け取ると、JSランタイムのためにメモリを割り当てます。When the JS engine receives an initialization request, it allocates memory for the JS run time. Figure 1.2 illustrates this process:

図1.2

ランタイムは、あなたのアプリケーションで使用される変数、オブジェクト、およびコンテキストが維持されるスペースです。 コンテキストはJSエンジンによって使用されるスレッドのためのスクリプト実行状態です。 それぞれのスクリプトかスレッドには、それ自身のコンテキストがなければなりません。 一つのJSランタイムは、多くのコンテキスト、オブジェクト、および変数を含むことができます。The run time is the space in which the variables, objects, and contexts used by your application are maintained. A context is the script execution state for a thread used by the JS engine. Each simultaneously existent script or thread must have its own context. A single JS run time may contain many contexts, objects, and variables.

JSエンジンを呼び出すほぼすべての場合で、コンテキストを引数として必要とします。そのため、アプリケーションでランタイムを作った後、最初に実行しなければいけないことの１つがJS_NewContextによりコンテキストを少なくとも1つ作ることになります。実際にコンテキストをいくつ必要とするかは、アプリケーション内でスクリプトをいくつ使おうとしているかに決まります。アプリケーション内で同時に実行するスクリプト1つごとに、1つのコンテキストが必要になります。その一方、アプリケーションが実行中の任意の時点で実行されるスクリプトが1つだけであれば、コンテキストを1つ作り、そのコンテキストをスクリプトごとに再利用することもできます。 Almost all JS engine calls require a context argument, so one of the first things your application must do after creating the run time is call <code>JS_NewContext</code> at least once to create a context. The actual number of contexts you need depends on the number of scripts you expect to use at the same time in your application. You need one context for each simultaneously existing script in your application. On the other hand, if only one script at a time is compiled and executed by your application, then you need only create a single context that you can then reuse for each script.

通常の場合、コンテキストを作ったあと、JSエンジンに最初から組みこまれているオブジェクトをJS_InitStandardClassesにより初期化することになります。 ほとんどのスクリプトで使われるArray, Boolean, Date, Math, Number, Stringが最初から組み込まれています。 After you create contexts, you will usually want to initialize the built-in JS objects in the engine by calling <code>JS_InitStandardClasses</code>. The built-in objects include the <code>Array</code>, <code>Boolean</code>, <code>Date</code>, <code>Math</code>, <code>Number</code>, and <code>String</code> objects used in most scripts.

アプリケーションは通常カスタムJSオブジェクトを使用します。カスタムJSオブジェクトは、アプリケーションの必要性に応じて作られるオブジェクトです。 カスタムオブジェクトには、アプリケーションを実行するために使われるデータ構造やメソッドに対応します。 カスタムJSオブジェクトを作るためには、オブジェクトに対応するJSクラスを実装し、JS_InitClassを呼び出すことによりランタイムに作成したクラスを登録し、 そのあと、JS_NewObjectを呼び出すことにより作成したカスタムオブジェクトのインスタンスを作る必要があります。 最後に、作成したオブジェクトがプロパティーを持つ場合には、JS_SetPropertyを呼び出すことにより、プロパティーのデフォルト値を設定する必要があるかも知れません。 Most applications will also use custom JS objects. These objects are specific to the needs of your applications. They usually represent data structures and methods used to automate parts of your application. To create a custom object, you populate a JS class for the object, call <code>JS_InitClass</code> to set up the class in the run time, and then call <code>JS_NewObject</code> to create an instance of your custom object in the engine. Finally, if your object has properties, you may need to set the default values for them by calling <code>JS_SetProperty</code> for each property. オブジェクトを作る際には、JSエンジンに対して特定のコンテキストを渡すことになりますが、オブジェクトは、コンテキストとは独立にランタイムの中に存在します。 オブジェクトをアクセスするためには、任意のスクリプトと、任意のコンテキストを対応させることができます。図 1.3 は、スクリプトに対する、ランタイムと、コンテキストと、オブジェクトの関係を示しています。 Even though you pass a specific context to the JS engine when you create an object, an object then exists in the run time independent of the context. Any script can be associated with any context to access any object. Figure 1.3 illustrates the relationship of scripts to the run time, contexts, and objects.

Figure 1.3

図1.3 が示しているように、同一のオブジェクトをアクセスする場合でも、スクリプトとコンテキストは全く独立して存在できます。 アプリケーションは、オブジェクトにアクセスするとき、同一のランタイムに属しているのであれば、 オブジェクトに割り当てられていないコンテキストを使うことができます。あるコンテキストとオブジェクトを、特定の目的だけに予約しておきたいような場合には、 アプリケーション内で別々のランタイムを作って下さい。 1つは、共有のコンテキストとオブジェクトのためのランタイムであり、 もう1つは(必要に応じて複数も可能)、特定の目的のコンテキストとオブジェクト用のランタイムになります。 As Figure 1.3 also illustrates, scripts and contexts exist completely independent from one another even though they can access the same objects. Within a given run time, an application can always use any use any unassigned context to access any object. There may be times when you want to ensure that certain contexts and objects are reserved for exclusive use. In these cases, create separate run times for your application: one for shared contexts and objects, and one (or more, depending on your application's needs) for private contexts and objects.

NOTE:あるコンテキストに、ある瞬間にアクセスできるスレッドはただ1つだけであることに注意。 '''NOTE''': Only one thread at a time should be given access to a specific context.

エンジンをビルドする

== Building the Engine ==

アプリケーションでJSを使うには、JSエンジンを共有ライブラリとしてビルドしなければなりません。ほとんどの場合、自動的にエンジンがビルドできる ようにメイクファイルが作られています。 Before you can use JS in your applications, you must build the JS engine as a shareable library. In most cases, the engine code ships with make files to automate the build process.

例えば、Unixの場合、JSのソースディレクトリには、Makefile.refというGNU make用のメイクファイルと、configディレクトリがあります。 config ディレクトリには、Makefile.refとともに使われる、 いろいろなプラットフォーム用の.mkファイルが用意されています。Windows NTの場合には、js.makというnmake ファイルが用意されています。 For example, under Unix, the js source directory contains a base gnu make file called <code>Makefile.ref</code>, and a <code>config</code> directory. The <code>config</code> directory contains platform-specific <code>.mk</code> files to use with <code>Makefile.ref</code> for your environment. Under Windows NT the nmake file is <code>js.mak</code>.

ソースディレクトリにあるreadmeファイルをチェックしてください。 Always check the source directory for any <code>readme</code> files that may contain late-breaking or updated compilation instructions or information.

What Are the Requirements for Engine Embedding?

アプリケーションでJavaScriptを使えるようにするためには、アプリケーションでエンジンを適切に呼び出す必要があります。 少なくとも次の5つの呼び出しを行う必要があります。

1. #include "jsapi.h"をCのモジュールに追加し、コンパイラがエンジンの呼び出しを行えるようにします。JSエンジンを特別な方法で使うような場合に、他のJSのソースコードを呼び出す必要がある場合があります。 例えば、アプリケーションでデバッガを呼び出すような場合には、jsdbgapi.hをアプリケーションのモジュールでインクルードする 必要があります。 To make your application JS-aware, embed the appropriate engine calls in your application code. There are at least five steps to embedding: <ol> <li>Add <code>#include "jsapi.h"</code> to your C modules to ensure that the compiler knows about possible engine calls. Specialized JS engine work may rarely require you to include additional header files from the JS source code. For example, to include JS debugger calls in your application, code you will need to include <code>jsdbgapi.h</code> in the appropriate modules. JSのソースコードの他のほとんどのヘッダファイルは、インクルードするべきではありません。他のヘッダファイルをインクルードすると リリースごとに変更する可能性があるエンジンの内部の実装に依存することになってしまいます。
2. アプリケーションで利用する構造体と変数を定義して下さい。例えば、JSエンジンにスクリプトを渡そうと考えているのであれば、アプリケーションでスクリプトの テキストデータを格納する文字列を用意して下さい。構造体と変数は、jsapi.hで定義されているJSのデータ型を使って定義して下さい。
3. JavaScriptで、アプリケーション特有のオブジェクトを作ってください。特に、アプリケーションでJS園児を使って処理の自動化を行うような場合には、 スクリプトで利用するアプリケーション特有のオブジェクトは、Cプログラムで使う構造体とメソッドに対応します。
4. 組み込み済みのJSオブジェクトを初期化するコードやアプリケーションで利用するオブジェクトが利用できるように、JSエンジンのAPIと変数を適切に組み込んで下さい。
5. ほとんどのJSエンジンのAPIは、戻り値を返します。戻り値が、0かNULLである場合には、エラーの種別を表します。このような戻り値が 0でない場合には、APIの呼び出しが成功したことを意味します。APIの呼び出しが成功した場合、戻り値は、アプリケーションが後で利用するために保存しておくべきオブジェクトへのポインタである場合が多いです。最低でも、アプリケーションでAPIの呼び出し後、どんな場合でも戻り値のチェックを行うべきです。

Most other header files in the JS source code should ''not'' be included. To do so might introduce dependencies based on internal engine implementations that might change from release to release.</li> <li>Provide support structures and variable declarations in your application. For example, if you plan on passing a script to the JS engine, provide a string variable to hold the text version of the script in your application.Declare structures and variables using the JS data types defined in <code>jsapi.h</code>.</li> <li>Script application-specific objects using JavaScript. Often these objects will correspond to structures and methods that operate on those structures in your C programs, particularly if you are using the JS engine to automate your application.</li> <li>Embed the appropriate JS engine API calls and variable references in your application code, including calls to initialize the built-in JS objects, and to create and populate any custom objects your application uses.</li> <li>Most JS engine calls return a value. If this value is zero or <code>NULL</code>, it usually indicates an error condition. If the value is nonzero, it usually indicates success; in these cases, the return value is often a pointer that your application needs to use or store for future reference. At the very least, your applications should always check the return values from JS engine calls.</li> </ol><

次に示すコードで、JSスクリプトを作る以外の、組み込みステップのほとんどを示しています。スクリプトを作り、JavaScript言語そのもののオブジェクトに関する 情報は、Client-Side JavaScript Guideを読んで下さい。サーバ側のオブジェクトに関しては、Server-Side JavaScript Guideを読んで下さい。

The following code fragment illustrates most of these embedding steps, except for the creation of JS scripts, which lies outside the scope of the introductory text. For more information about creating scripts and objects using the JavaScript language itself, see the ''Client-Side JavaScript Guide''. For further information about scripting server-side objects, see the ''Server-Side JavaScript Guide''.

.
.
.
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

/* include the JS engine API header */
#include "jsapi.h"
.
.
.

/* main function sets up global JS variables, including run time,
 * a context, and a global object, then initializes the JS run time,
 * and creates a context. */

int main(int argc, char **argv)
{
  int c, i;
  /*set up global JS variables, including global and custom objects */

  JSVersion version;
  JSRuntime *rt;
  JSContext *cx;
  JSObject  *glob, *it;
  JSBool builtins;

  /* initialize the JS run time, and return result in rt */
  rt = JS_NewRuntime(8L * 1024L * 1024L);

  /* if rt does not have a value, end the program here */
  if (!rt)
    return 1;

  /* create a context and associate it with the JS run time */
  cx = JS_NewContext(rt, 8192);

  /* if cx does not have a value, end the program here */
  if (cx == NULL)
    return 1;

  /* create the global object here */
  glob = JS_NewObject(cx, clasp, NULL, NULL);

  /* initialize the built-in JS objects and the global object */
  builtins = JS_InitStandardClasses(cx, glob);

  .
  . 
  .

  return 0;

}

この例は、JSエンジンをアプリで使うために必要な、主要な部分を単純化したものです。より完全な例は、js.cを見て下さい。これは、JSエンジンのソースに ある、サンプルアプリケーションです。 This example code is simplified to illustrate the key elements necessary to embed JS engine calls in your applications. For a more complete example -- from which these snippets were adapted -- see <code>js.c</code>, the sample application source code that is included with the JS engine source code.

Understanding Key Embedding Concepts

アプリケーションでJavaScriptを使う用にする場合、ほとんどの場合で、JS APIをつかう標準的な使い方に従うことになるでしょう。 本セクションは、アプリケーションに組み込む必要のあるAPIの呼び出し方について記述しています。 For most of the JavaScript aware applications you create, you will want to follow some standard JS API embedding practices. The following sections describe the types of API calls you need to embed in all your applications.

多くの場合、正しく組みオムためには、ある種のAPIを正しい順序で呼び出すことが重要です。例えば、JSランタイムを初期化した後に、他のAPIを呼びださなければ なりません。同様に、アプリケーションが終了する前に、JSランタイムを開放すべきです。従って、アプリケーションのmain関数は、JSランタイムの初期化で始まったあと アプリケーション固有の処理を行ったあと、JSランタイムの開放処理で終わるように作られるべきです。 In many cases, the order in which you embed certain API calls is important to successful embedding. For example, you must initialize a JS run time before you can make other JS calls. Similarly, you should free the JS run time before you close your application. Therefore, your application's '''main''' function typically sandwiches API calls for initializing and freeing the JS run time around whatever other functionality you provide:

int main(int argc, char **argv)
{
  int c, i;

  /*set up global JS variables, including global and custom objects */
  JSVersion version;
  JSRuntime *rt;
  JSContext *cx;
  JSObject  *glob, *it;

  .
  .
  .

  /* initialize the JS run time, and return result in rt */
  rt = JS_NewRuntime(8L * 1024L * 1024L);

  /* if rt does not have a value, end the program here */
  if (!rt)
    return 1;

  .
  .
  .

  /* establish a context */
  cx = JS_NewContext(rt, 8192);

  /* if cx does not have a value, end the program here */
  if (cx == NULL)
    return 1;

  /* initialize the built-in JS objects and the global object */
  builtins = JS_InitStandardClasses(cx, glob);

  .
  .
  .

  /* include your application code here, including JS API calls
   * that may include creating your own custom JS objects. The JS
   * object model starts here. */

  .
  .
  .

  /* Before exiting the application, free the JS run time */
  JS_DestroyRuntime(rt);

この例で示したように、JSエンジンを組み込むアプリケーションは、JSランタイムをまずセットアップし、終了前に開放する責任があります。 一般的には、JSランタイムを初期化して開放するのは、アプリケーション内でJavaScriptを起動する主要なモジュールで実行するのが最も良い実装になるでしょう。 As this example illustrates, applications that embed calls to the JS engine are responsible for setting up the JS run time as one of its first acts, and they are responsible for freeing the run time before they exit. In general, the best place to ensure that the run time is initialized and freed is by embedding the necessary calls in whatever module you use as the central JS dispatcher in your application.

ランタイムを初期化した後、アプリケーションで利用するJSオブジェクトモデルを構築することになります。オブジェクトモデルとは、JSオブジェクト同士の関係を決めるものです。 JSオブジェクトは、もともと階層的に作られています。そのため、全てのJSオブジェクトは、デフォルトでは、グローバルオブジェクトに関係づけられています。 オブジェクトは、デフォルトで、グローバルオブジェクトから派生したものになります。標準的なJSクラスを初期化すると、グローバルオブジェクトが自動的に作られます。 After you initialize the run time, you can establish your application's JS object model. The object model determines how your JS objects relate to one another. JS objects are hierarchical in nature. All JS objects are related to the global object by default. They are descendants of the global object. You automatically get a global object when you initialize the standard JS classes:

builtins = JS_InitStandardClasses(cx, glob);

グローバルオブジェクトは、他のオブジェクトが継承する基本的なプロパティとメソッドを利用できるようにします。カスタムオブジェクトを作る際には、カスタムオブジェクトは、 グローバルオブジェクトで定義されているプロパティとメソッドを使うことができます。グローバルオブジェクトで定義されているデフォルトのプロパティとメソッドは、 デフォルトのママで使うことも、カスタムオブジェクトで再定義することもできます。 The global object sets up some basic properties and methods that are inherited by all other objects. When you create your own custom objects, they automatically use the properties and methods defined on the global object. You can override these default properties and methods by defining them again on your custom object, or you can accept the default assignments.

カスタムオブジェクトは、他の組み込み済みのJSオブジェクトを基にして実装することもできますし、他のカスタムオブジェクトを基に実装することができます。 いずれの場合でも、カスタムオブジェクトは、グローバルオブジェクトから始まる階層構造の中の親オブジェクトのプロパティとメソッドを継承します。 グローバルオブジェクトとカスタムオブジェクトに関する情報は、Initializing Built-in Global JS Objects とCreating and Initializng Custom Objects.を参照して下さい。 You can also create custom objects that are based on other built-in JS objects, or that are based on other custom objects. In each case, the object you create inherits all of the properties and methods of its predecessors in the hierarchical chain, all the way up to the global object. For more information about global and custom objects, see Initializing Built-in and Global JS Objects and Creating and Initializing Custom Objects.

ランタイムの管理

== Managing a Run Time == JSランタイムは、JSエンジンが使うコンテキスト、オブジェクト、JS関数とスクリプトに付随する変数のメモリ空間です。 JS関数やスクリプトを使馬えに、ランタイムの初期化を行う必要があります。ランタイムの初期化を行う、APIは、JS_NewRuntimeです。 JS_NewRuntimeの引数は１つであり、ガーベージコレクションが発生する前にランタイムに割り当てる最大のバイト数を符号なし整数で指定します。 例えば、 The JS run time is the memory space the JS engine uses to manage the contexts, objects, and variables associated with JS functions and scripts. Before you can execute any JS functions or scripts you must first initialize a run time. The API call that initializes the run time is <code>JS_NewRuntime}</code>. <code>JS_NewRuntime</code> takes a single argument, an unsigned integer that specifies the maximum number of bytes of memory to allocate to the run time before garbage collection occurs. For example:

 rt = JS_NewRuntime(8L * 1024L * 1024L);

この例が示すように、JS_NewRuntimeは、作られたランタイムへのポインタを返り値として返します。返り値が、NULLではない場合には、ランタイムの作成に成功したことを示します。 As this example illustrates, <code>JS_NewRuntime</code> also returns a single value, a pointer to the run time it creates. A non-NULL return value indicates successful creation of the run time.

通常の場合、1つのアプリケーションに、1つだけランタイムを必要とします。しかし、必要に応じてJS_NewRuntime を呼び出し、戻り値を別のポインタに格納することにより、複数のランタイムを作ることもできます。 Normally, you only need one run time for an application. It is possible, however, to create multiple run times by calling <code>JS_NewRuntime</code> as necessary and storing the return value in a different pointer.

JSランタイムが必要ではなくなったときには、ランタイムを破棄して、ランタイムが使っていたメモリ資源を他のアプリケーションが使えるようにするべきです。 アプリケーション内でJSをどのように使うかによって、使い終わったらすぐにランタイムを破棄することもできますし、ランタイムをアプリケーションの終了時まで破棄せずに とっておくこともできます。何れの場合でも、不要になったランタイムを開放するには、JS_DestroyRuntimeを使います。 この関数は、破棄するランタイムへのポインタを引数としてとります。 When the JS run time is no longer needed, it should be destroyed to free its memory resources for other application uses. Depending on the scope of JS use in your application, you may choose to destroy the run time immediately after its use, or, more likely, you may choose to keep the run time available until your application is ready to terminate. In either case, use the <code>JS_DestroyRuntime</code> to free the run time when it is no longer needed. This function takes a single argument, the pointer to the run time to destroy:

 JS_DestroyRuntime(rt);

複数のランタイムを使う場合には、それぞれのランタイムをアプリケーションの終了前に開放して下さい。 If you use multiple run times, be sure to free each of them before ending your application.

コンテクストの管理

== Managing Contexts == ほとんどのJS APIは、引数としてに、コンテキストを渡す必要があります。コンテキストは、JavaScriptエンジン内で、スクリプトに対応します。 エンジンは、スクリプトを実行するスレッドに、コンテキスト情報を渡します。同時に実行されるスクリプトには、スクリプトごとにコンテキストが割り当てられなければ なりません。スクリプトが実行を完了したときには、コンテキストは不要になり、コンテキストは新しいスクリプトに割り当てたり、開放したりすることができます。 Almost all JS API calls require you to pass a context as an argument. A context identifies a script in the JavaScript engine. The engine passes context information to the thread that runs the script. Each simultaneously-executing script must be assigned a unique context. When a script completes execution, its context is no longer in use, so the context can be reassigned to a new script, or it can be freed.

スクリプトを実行するために新しいコンテキストを作るときには、JS_NewContextを使います。この関数は、2つの引数をとります。 1つは、コンテキストと関連づけるランタイムへのポインタであり、もう1つは、コンテキストのスタックに割り当てるバイト数である。 コンテキストの作成に成功した場合には、新しくできあがったコンテキストへのポインタを返します。例： To create a new context for a script, use <code>JS_NewContext</code>. This function takes two arguments: a pointer to the run time with which to associate this context, and the number of bytes of stack space to allocate for the context. If successful, the function returns a pointer to the newly established context. For example:

 JSContext *cx;
 .
 .
 .
 cx = JS_NewContext(rt, 8192);

ランタイムは、呼び出し前に作っておかなければなりません。コンテキストを作る際に指定するスタックの大きさは、コンテキストを使って実行するスクリプトによって作られる変数やオブジェクトに合うだけの大きさがなければなりません。コンテキストを割り当てたり管理したりする際には、オーバヘッドがあるため、次のような事柄に注意を必要とします。 The run time must already exist. The stack size you specify for the context should be large enough to accommodate any variables or objects created by the script that uses the context. Note that because there is a certain amount of overhead associated with allocating and maintaining contexts you will want to:

1. アプリケーション内で、ある時点で必要とする数だけ、コンテキストを作成する
2. アプリケーションで使うかも知れないのであれば、コンテキストをとっておき、必要に応じてコンテキストを破棄したり、再作成したりしないこと

# Create only as many contexts as you need at one time in your application. # Keep contexts for as long as they may be needed in your application rather than destroying and recreating them as needed.

コンテキストが不要になったとき、割り当てられていたメモリ資源を開放し他のアプリケーションが使えるように、コンテキストを破棄すべきです。 アプリケーションでのコンテキストの使い方により、コンテキストが不要になったらすぐに破棄することもできますし、また、アプリケーションが終了するときまでコンテキストを破棄せずにとっておくこともできます。どちらの場合でも、JS_DestroyContextを使って、不要になったときには、コンテキストを破棄します。 この関数には、破棄するコンテキストへのポインタを引数として渡します。 When a context is no longer needed, it should be destroyed to free its memory resources for other application uses. Depending on the scope of JS use in your application, you may choose to destroy the context immediately after its use, or, more likely, you may choose to keep the context available for reuse until your application is ready to terminate. In either case, use the <code>JS_DestroyContext</code> to free the context when it is no longer needed. This function takes a single argument, the pointer to the context to destroy:

 JS_DestroyContext(cx);

アプリケーションが複数のランタイムを作るときには、アプリケーションの使っているコンテキストが、どのランタイムで使われているかを知る必要がでてくる場合がある。 このような場合には、引数としてコンテキストを渡してJS_GetRuntimeを呼び出してください。JS_GetRuntimeは、対応するランタイムへのポインタを返します。 If your application creates multiple run times, the application may need to know which run time a context is associated with. In this case, call <code>JS_GetRuntime</code>, and pass the context as an argument. <code>JS_GetRuntime</code> returns a pointer to the appropriate run time if there is one:

 rt = JS_GetRuntime(cx);

コンテキストを作るときには、コンテキストを使うスクリプトによって作られる変数やオブジェクトを格納するためのスタック領域を割り当てます。 スタック領域の使用量を最小にしながら、コンテキストに大容量のデータを格納することもできます。JS_SetContextPrivateを呼ぶことで、コンテキストに プライベートデータへのポインタを格納できます。データにアクセスするためにプライベートポインタを取得するときには、JS_GetContextPrivateを呼んでください。プライベートデータの構築や管理は、アプリケーションで行う必要があります。 When you create a context, you assign it stack space for the variables and objects that get created by scripts that use the context. You can also store large amounts of data for use with a given context, yet minimize the amount of stack space you need. Call <code>JS_SetContextPrivate</code> to establish a pointer to private data for use with the context, and call <code>JS_GetContextPrivate</code> to retrieve the pointer so that you can access the data. Your application is responsible for creating and managing this optional private data.

プライベートデータを作りコンテキストに関連付けるためには、次のことを行ってください。 To create private data and associate it with a context:

1. C 言語の void　ポインタ変数としてプライベートデータをつくる
2. プライベートデータを格納するコンテキストと、プライベートデータを引数として[[JS_SetContextPrivate[[を呼ぶ

# Establish the private data as you would a normal C void pointer variable. # Call <code>JS_SetContextPrivate</code>, and specify the context for which to establish private data, and specify the pointer to the data.

例： For example:

 JS_SetContextPrivate(cx, pdata);

後でプライベートデータを取得する場合には、コンテキストを引数としてJS_GetContextPrivateを呼び出してください。 この関数は、プライベートデータへのポインタを返します。 To retrieve the data at a later time, call <code>JS_GetContextPrivate</code>, and pass the context as an argument. This function returns the pointer to the private data:

 pdata = JS_GetContextPrivate(cx);

JSのグローバルオブジェクトの初期化

== Initializing Built-in and Global JS Objects ==

JavaScriptエンジンには、開発が簡単にできるようにするため、組み込み済みのオブジェクトが実装されています。 例えば、Arrayオブジェクトを使うことで、配列を簡単に作って使うことができるようになっています。 また、Dateオブジェクにより、日付を統一的に扱えるようになっています。エンジンに実装されている組み込み済みのオブジェクトのリストは、 JS_InitStandardClassのエントリーを参照すると見つかります。 The JavaScript engine provides several built-in objects that simplify some of your development tasks. For example, the built-in <code>Array</code> object makes it easy for you to create and manipulate array structures in the JS engine. Similarly, the Date object provides a uniform mechanism for working with and handling dates. For a complete list of built-in objects supported in the engine, see the reference entry for <code>JS_InitStandardClasses</code>.

JSエンジンは、関数オブジェクトとグローバルオブジェクトを使います。一般的には、グローバルオブジェクトは、アプリケーションの中で グローバルオブジェクト以外のすべてのオブジェクトとグローバル変数のためのデフォルトのスコープの役割を果たします。 アプリケーション用のオブジェクトを作る前に、グローバルオブジェクトの初期化を行うことになるでしょう。関数オブジェクトは、オブジェクトの コンストラクタに利用されます。 The JS engine always uses function and global objects. In general, the global object resides behind the scenes, providing a default scope for all other JS objects and global variables you create and use in your applications. Before you can create your own objects, you will want to initialize the global object. The function object enables objects to have and call constructors.

JS_InitStandardClassessを呼ぶことで、グローバルオブジェクト、関数オブジェクトと組み込み済みのエンジン用の オブジェクトが初期化され、アプリケーションでこれらのオブジェクトを使うことができるようになります。 A single API call, <code>JS_InitStandardClasses</code>, initializes the global and function objects and the built-in engine objects so that your application can use them:

 JSBool builtins;
 .
 .
 .
 builtins = JS_InitStandardClasses(cx, glob);

JS_InitStandardClasses を呼び出すと、初期化が成功したかどうかをJSのブール型で返します。 <code>JS_InitStandardClasses</code> returns a JS boolean value that indicates the success or failure of the initialization.

アプリケーションは、別のグローバルオブジェクトを使うこともできます。例えば、Netscape Navigatorは、Netscape Navigator専用のグローバルオブジェクトである、windowオブジェクトを使っています。アプリケーションでグローバルオブジェクトを変更するときには、 JS_SetGlobalObjectを使ってください。より詳しい情報は、JS_GetGlobalObjectの項を参照してください。 You can specify a different global object for your application. For example, the Netscape Navigator uses its own global object, window. To change the global object for you application, call <code>JS_SetGlobalObject</code>. For more information, see the reference entry for <code>JS_SetGlobalObject</code>.

Creating and Initializing Custom Objects

内蔵されているオブジェクトと共に、カスタムJSオブジェクトを作成して、初期化して、使用することができます。 あなたがあなたのアプリケーションを自動化するために、JSエンジンを使用しているなら、特に必要でしょう。 カスタムJSオブジェクトは、ダイレクトに、またはそれらはインタフェースとして、プログラム・サービスを提供することができます。例えば、ネットワークアクセスを扱ったり、データベース・サービス扱ったりするかもしれません。 また、データを反映するJSオブジェクトは、オブジェクト指向インタフェースを、厳密に言うとオブジェクト指向でないCコードに提供するかもしれません。 そのようなカスタムオブジェクトはインタフェースとしてアプリケーション自体に作用します、アプリケーションからユーザと、それを返す前の受信と処理ユーザ入力からアプリケーションまで値を通過して。 また、そのようなオブジェクトは、アクセスコントロールをアプリケーションの基本的な機能に提供するのに使用されるかもしれません。In addition to using the engine's built-in objects, you will create, initialize, and use your own JS objects. This is especially true if you are using the JS engine with scripts to automate your application. Custom JS objects can provide direct program services, or they can serve as interfaces to your program's services. For example, a custom JS object that provides direct service might be one that handles all of an application's network access, or might serve as an intermediary broker of database services. Or a JS object that mirrors data and functions that already exist in the application may provide an object-oriented interface to C code that is not otherwise, strictly-speaking, object-oriented itself. Such a custom object acts as an interface to the application itself, passing values from the application to the user, and receiving and processing user input before returning it to the application. Such an object might also be used to provide access control to the underlying functions of the application.

カスタムJSオブジェクトを作成するには、2つの方法があります:There are two ways to create custom objects that the JS engine can use:

• オブジェクト（のプロパティーやメソッドやコンストラクタ）を作成するJSスクリプトを書き、アプリケーションの実行時にそのスクリプトを実行します。Write a JS script that creates an object, its properties, methods, and constructor, and then pass the script to the JS engine at run time.
• アプリケーションに、オブジェクトのメソッドとプロパティーを定義するコードを埋め込みます。そしてエンジンをコールし、新しいオブジェクトを初期化します。さらにコールして、オブジェクトのプロパティーを設定します。 この方法の利点は、あなたのアプリケーションが直接オブジェクトの埋め込みを操るネイティブのメソッドを含むことができるということです。Embed code in your application that defines the object's properties and methods, call the engine to initialize a new object, and then set the object's properties through additional engine calls. An advantage of this method is that your application can contain native methods that directly manipulate the object embedding.

どちらの場合でも、ガベレージコレクションでオブジェクトが消えないようにしたいならば、JS_AddRoot か JS_AddNamedRootを呼ぶことによって、オブジェクトを根づかせなければなりません。In either case, if you create an object and then want it to persist in the run time where it can be used by other scripts, you must root the object by calling <code>JS_AddRoot</code> or <code>JS_AddNamedRoot</code>. Using these functions ensures that the JS engine will keep track of the objects and clean them up during garbage collection, if appropriate.

== Creating an Object From a Script ==

スクリプトからオブジェクトを作る

スクリプトが実行中にだけ存在するようなオブジェクトを必要とするときには、スクリプトからカスタムJSオブジェクトを作るとよいです。 スクリプトを何度か呼び出す間存在し続けるオブジェクトを作るために、スクリプトを使う代わりにアプリケーションにオブジェクトを埋め込むことができます。 One reason to create a custom JS object from a script is when you only need an object to exist as long as the script that uses it is executing. To create objects that persist across script calls, you can embed the object code in your application instead of using a script.

NOTE: 永続的なオブジェクトを作るときにもスクリプトを使うことができます。 '''NOTE''': You can also use scripts to create persistent objects, too.

スクリプトを使ってカスタムオブジェクトを作るには：

例：

To create a custom object using a script: <ol> <li>Define and spec the object. What is it intended to do? What are its data members (properties)? What are its methods (functions)? Does it require a run time constructor function?</li> <li>Code the JS script that defines and creates the object.</li> For example:

     function myfun(){
       var x = newObject();
       .
       .
       .
     }

NOTE: JavaScriptを使ったobject scriptingは、アプリケーションにJSエンジンを組み込むという話とは別の話題となります。 そのためobject scriptingの情報については、Client-Side JavaScript Guide とServer-side JavaScript Guideをご覧ください。 '''NOTE''': Object scripting using JavaScript occurs outside the context of embedding the JS engine in your applications. For more information about object scripting, see the ''Client-Side JavaScript Guide'' and the ''Server-Side JavaScript Guide''.

アプリケーションの中で、スクリプトをコンパイルし実行するために適切にJSエンジンを呼び出すようにしてください。呼び出し方には、2種類の方法があります。1.) JS_EvaluateScriptとJS_EvaluateUCSScriptを使ってコンパイルし実行する方法.

1. オブジェクトを定義し、specしてください。つまり、オブジェクトが何をしようとしているか？オブジェクトのメンバ(プロパティ)は何か？オブジェクトのメソッド(関数)は何か？ オブジェクトは実行時にコンストラクタを必要とするか？を指定します。
2. そのようなオブジェクトを定義して、オブジェクトを作成するようなコードを作ってください。
3. 2.) JS_CompileScriptかJS_CompileUCSScriptを使って、一度スクリプトをコンパイルし、JS_ExecuteScriptを使って繰り返し実行する方法。"UC"がついている方は、UNICODEでエンコードされているスクリプトのために用意されています。

Embed the appropriate JS engine call(s) in your application to compile and execute the script. You have two choices: 1.) compile and execute a script with a single call to <code>JS_EvaluateScript</code>, <code>JS_EvaluateUCScript</code> or 2.) compile the script once with a call to <code>JS_CompileScript</code> or <code>JS_CompileUCScript</code>, and then execute it repeatedly with individual calls to <code>JS_ExecuteScript</code>. The "UC" versions of these calls provide support for Unicode-encoded scripts.</li> </ol>

スクリプトを使って作ったオブジェクトは、スクリプトが実行されている間だけ利用できるようにもできますし、スクリプトの実行が終わったあとも利用できるようにもできます。 普通は、スクリプトの実行が終わると、オブジェクトは破棄されます。多くの場合、この動作がアプリケーションで必要となる動作です。その一方、複数のスクリプトを動かしている 間や、あるいは、 アプリケーションが動き続けている間にも、オブジェクトが破棄されずに残っていてほしいこともあるでしょう。そのような場合には、アプリケーションにオブジェクトを作る コードを直接組み込むか、グローバルオブジェクトが存在している間、オブジェクトが破棄されないように、オブジェクトをグローバルオブジェクトにしておく必要があります。 An object you create using a script only can be made available only during the lifetime of the script, or can be created to persist after the script completes execution. Ordinarily, once script execution is complete, its objects are destroyed. In many cases, this behavior is just what your application needs. In other cases, however, you will want object persistence across scripts, or for the lifetime of your application. In these cases you need to embed object creation code directly in your application, or you need to tie the object directly to the global object so that it persists as long as the global object itself persists.

アプリケーションにカスタムオブジェクトを組み込む

== Embedding a Custom Object in an Application ==

オブジェクトが永続的に存在していることが求められる場合や、オブジェクトが複数のスクリプトの実行中にも利用できるようになっている方が望ましいときには、アプリケーションにカスタムJSオブジェクトを組み込むと、便利です。例えば、ユーザIDとアクセス権をあらわすようなオブジェクトがアプリケーションのライフタイム中に必要となる場合です。 スクリプト内でユーザIDとアクセス権をチェックする必要ができるたびに、オブジェクトを 作るのと比較して、カスタムオブジェクトを作ってアプリケーションに組み込んで、1度利用できるようにしておくと、実行時のオーバヘッドと実行時間を減らすことができます。 Embedding a custom JS object in an application is useful when object persistence is required or when you know that you want an object to be available to several scripts. For example, a custom object that represents a user's ID and access rights may be needed during the entire lifetime of the application. It saves overhead and time to create and populate this object once, instead of recreating it over and over again with a script each time the user's ID or permissions need to be checked.

アプリケーションにカスタムオブジェクトを組み込む1つの方法は次の通りです: One way to embed a custom object in an application is to:

1. JSPropertySpecデータ型を作りオブジェクトのプロパティ情報にします。プロパティ情報には、プロパティーの名前と、get/set メソッドが入ります。
2. JSFunctionSpecデータ型を作り、オブジェクトのメソッドとして使えるようにします。
3. オブジェクトのメソッドを呼び出したときに実際に実行されるC言語の関数を作ります。
4. JS_NewObjectかJS_ConstructObjectを呼び、オブジェクトのインスタンスを作ります。
5. 　JS?DefineFunctionsを呼び、オブジェクトのメソッドを作ります。
6. JS_DefinePropertiesを呼び、オブジェクトのプロパティを作ります。

# Create a <code>JSPropertySpec</code> data type, and populate it with the property information for your object, including the name of the property's get and set methods. # Create a <code>JSFunctionSpec</code> data type, and populate it with information about the methods used by your object. # Create the actual C functions that are executed in response to your object's method calls. # Call to <code>JS_NewObject</code> or <code>JS_ConstructObject</code> to instantiate the object. # Call <code>JS_DefineFunctions</code> to create the object's methods. # Call <code>JS_DefineProperties</code> to create the object's properties.

永続的に存在するカスタムJSオブジェクトは、このオブジェクトの存在を必要とする他のコードが実行できるようにするため、アプリケーションの先頭付近におくべきです。 カスタムオブジェクトのインスタンスを作り、使えるようにするための組み込みエンジンの呼び出しを行う部分も、オブジェクトの存在を必要とする他のコードより前に 実行するべきです。 The code that describes persistent, custom JS objects should be placed near the start of application execution, before any code that relies upon the prior existence of the object. Embedded engine calls that instantiate and populate the custom object should also appear before any code that relies on the prior existence of the object.

NOTE: 多くの場合により簡単にカスタムオブジェクトを作る方法として、JS_DefineObjectを使ってオブジェクトを作る方法もあります。オブジェクトを 作った後、繰り返しJS_SetPropertyを呼び、オブジェクトにプロパティを追加します。オブジェクトを定義するより詳しい方法については、JS_DefineObjectを参照ください。オブジェクトにプロパティーを追加する方法については、JS_SetPropertyをご覧ください。 '''NOTE''': An alternate, and in many cases, easier way to create a custom object in application code is to call <code>JS_DefineObject</code> to create the object, and then make repeated calls to <code>JS_SetProperty</code> to set the object's properties. For more information about defining an object, see <code>JS_DefineObject</code> . For more information about setting an object's properties, see <code>JS_SetProperty</code>.

Providing Private Data for Objects

コンテキストでできたのと同様に、オブジェクトのデータ構造自体にデータを保存せずに、オブジェクトに大きなデータを関連づけることができます。 JS_SetPrivateを使うことでオブジェクトのプライベートデータに、ポインタを格納できます。また、プライベートデータに格納してあるデータに アクセスするためにポインタを取得するには、JS_GetPrivateを呼び出して下さい。アプリケーションは、オプションで利用できるプライベートデータを 作成し、管理する責務を持ちます。 Like contexts, you can associate large quantities of data with an object without having to store the data in the object itself. Call <code>JS_SetPrivate</code> to establish a pointer to private data for the object, and call <code>JS_GetPrivate</code> to retrieve the pointer so that you can access the data. Your application is responsible for creating and managing this optional private data.

プライベートデータを作成し、オブジェクトに関連づけるには: To create private data and associate it with an object:

1. プライベートデータを通常のC言語のvoid ポインタ変数として作成します。
2. JS_SetPrivate関数を呼び、プライベートデータと関連づけるオブジェクトと、プライベートデータ自身のポインタを指定して、JS_SetPrivate関数を呼びます。

# Establish the private data as you would a normal C void pointer variable. # Call <code>JS_SetPrivate</code>, specify the object for which to establish private data, and specify the pointer to the data.

例： For example:

 JS_SetPrivate(cx, obj, pdata);

データを後で使うためには、オブジェクトを引数としてJS_GetPrivateを呼びます。この関数は、オブジェクトの婦リベートデータへのポインタを返します。 To retrieve the data at a later time, call <code>JS_GetPrivate</code>, and pass the object as an argument. This function returns the pointer to an object's private data:

 pdata = JS_GetPrivate(cx, obj);

Handling Unicode

現在のJSエンジンは、JS関数を含むスクリプトを処理する多くのAPIで、UNICODEを扱うことができます。 これらの関数は、UNICODEでエンコードされたスクリプトを直接エンジンに渡し、コンパイルして実行することができます。 次の表は、従来からある関数とそのUNICODE版の一覧です。 The JS engine now provides Unicode-enabled versions of many API functions that handle scripts, including JS functions. These functions permit you to pass Unicode-encoded scripts directly to the engine for compilation and execution. The following table lists standard engine functions and their Unicode equivalents:

UNICODE版の関数は、同じ名前のUNICODE版ではない関数とまったく同じように動作します。ただし、UNICODE版ではない関数は、char *を引数としてとりますが、UNICODE版は、jschar *を引数として使います。 Unicode-enabled functions work exactly like their traditional namesakes, except that where traditional functions take a <code>char *</code> argument, the Unicode versions take a <code>jschar *</code> argument.

Working with JS Data Types

JavaScriptでは、独自の型を定義しています。JavaScriptの型の中には、直接C言語の型に対応しているものもあります。 直接C言語の型に対応していないような、JSObjectやjsdoubleや、JSStringなどの 型は、JavaScriptに特有のものです。 JavaScript defines its own data types. Some of these data types correspond directly to their C counterparts. Others, such as <code>JSObject</code>, <code>jsdouble</code>, and <code>JSString</code>, are specific to JavaScript.

一般的には、アプリケーションで使う型は、C言語でもそうするように、宣言する必要があります。しかし、JSエンジンは、格納するのに1ワード 以上の領域を必要とするJSObjectや,jsdoubleやJSStringなどは、別々に 管理します。エンジンは定期的にこれらの変数が、使われているかどうかを確認し、使われていない場合には、ガーベージコレクトし、再利用します。 Generally, you declare and use JS data types in your application just as you do standard C data types. The JS engine, however, keeps separate track of JS data type variables that require more than a word of storage: <code>JSObject</code>, <code>jsdouble</code>, and <code>JSString</code>. Periodically, the engine examines these variables to see if they are still in use, and if they are not, it garbage collects them, freeing the storage space for reuse.

ガーベージコレクションを行うことで、ヒープを効率的に再利用できるようになります。しかし、過度にフラグメントしていると、性能面での 問題を発生させます。アプリケーションで使うJSの変数とオブジェクトの数に基づいてアプリケーションで確保したJSランタイムの大きさを元に、 ガーベージコレクションを行う大体の頻度を制御することができます。アプリケーションでたくさんのJSオブジェクトと変数を使う場合には、 頻繁にガーベージコレクションが頻繁に実行されないように十分に大きなランタイムを割り当て方がよいでしょう。 Garbage collection makes effective reuse of the heap, but overly frequent garbage collection may be a performance issue. You can control the approximate frequency of garbage collection based on the size of the JS run time you allocate for your application in relation to the number of JS variables and objects your application uses. If your application creates and uses many JS objects and variables, you may want to allocate a sufficiently large run time to reduce the likelihood of frequent garbage collection.

NOTE+ アプリケーションは、JS_GCか、JS_MaybeGCを呼ぶことで、いつでも強制的にガーベージコレクションを実行することができます。JS_GCは、強制的にガーベージコレクションを実行します。JS_MaybeGCは、呼び出したときに、最初にランタイムに割り当てた領域のうち一定の割合の領域が使用中であった場合に実際にガーベージコレクションを行います。 '''NOTE''': Your application can also call <code>JS_GC</code> or <code>JS_MaybeGC</code> to force garbage collection at any time. <code>JS_GC</code> forces garbage collection. <code>JS_MaybeGC</code> performs conditional garbage collection only if a certain percentage of space initially allocated to the run time is in use at the time you invoke the function.

Working with JS Values

JSのデータ型の他に、JSエンジンは、jsvalというJSの値も使用します。jsvalは、本質的には 整数以外の値として使われるときは、JSデータ型へのポインタです。整数として使われるときには、jsvalは、その整数の 値そのものを格納しています。整数以外の値を格納しているときには、その値へのポインタに型の情報が付け加えられたものを保持します。これは、 エンジンの効率をよくするためと、多くのAPIで、いろいろなデータ型を扱えるようにするためです。 In addition to JS data types, the JS engine also uses JS values, called <code>jsval</code>s. A <code>jsval</code> is essentially a pointer to any JS data type except integers. For integers, a <code>jsval</code> contains the integer value itself. In other cases, the pointer is encoded to contain additional information about the type of data to which it points. Using <code>jsval</code>s improves engine efficiency, and permits many API functions to handle a variety of underlying data types.

エンジンのAPIには、次に示すような、jsvalのデータ型をテストするための一連のマクロを提供しています。 The engine API contains a group of macros that test the JS data type of a <code>jsval</code>. These are:

• JSVAL_IS_OBJECT
• JSVAL_IS_NUMBER
• JSVAL_IS_INT
• JSVAL_IS_DOUBLE
• JSVAL_IS_STRING
• JSVAL_IS_BOOLEAN

上記マクロを使って jsvalが格納している実際のデータ型をテストすることに加え、JSVAL_IS_PRIMITIVEを 使うことで、JSのプリミティブデータ型であるかどうかのテストを行うこともできます。プリミティブとは、undefinedか、 null か、ブール型か 数値型か、文字列型のことを言います。 Besides testing a <code>jsval</code> for its underlying data type, you can test it to determine if it is a primitive JS data type (<code>JSVAL_IS_PRIMITIVE</code>). Primitives are values that are undefined, null, boolean, numeric, or string types.

jsvalが指している値が、NULL)JSVAL_IS_NULL)であるかどうかと、 void )JSVAL_IS_VOID)であるかを調べる事もできます。 You can also test the value pointed to by a <code>jsval</code> to see if it is <code>NULL</code> (<code>JSVAL_IS_NULL</code>) or void (<code>JSVAL_IS_VOID</code>).

jsvalがさしているJSデータ型が、JSObjectか、jsdoubleか、jsstrである場合には、jsvalを、それぞれ、JSVAL_TO_OBJECT, JSVAL_TO_DOUBLEJSVAL_TO_STRINGを使って実際に格納しているデータへのポインタにキャストすることができます。この機能は、アプリケーションやJSエンジンが特定のデータ型の変数や引数を必要とする場合に使われます。 同様のことがJSObjectをOBJECT_TO_JSVAL, DOUBLE_TO_JSVAL, <ode>STRING_TO_JSVAL</code>を使って変換できます。

If a jsval points to a JS data type of <code>JSObject</code>, <code>jsdouble</code>, or <code>jsstr</code>, you can cast the <code>jsval</code> to its underlying data type using <code>JSVAL_TO_OBJECT</code>, <code>JSVAL_TO_DOUBLE</code>, and <code>JSVAL_TO_STRING</code>, respectively. This is useful in some cases where your application or a JS engine call requires a variable or argument of a specific data type, rather than a <code>jsval</code>. Similarly, you can convert a <code>JSObject</code>, <code>jsdouble</code>, and <code>jsstr</code> to a <code>jsval</code> using <code>OBJECT_TO_JSVAL</code>, <code>DOUBLE_TO_JSVAL</code>, and <code>STRING_TO_JSVAL</code>, respectively.

Unicode String Support

他のAPIの場合と同じように、UNICODE版の文字列関数の名前は、標準的な文字列関数の名前と1対1に対応します。 標準的な関数名が、JS_NewStringCopyNである場合には、対応するUNICODE版の関数名は、 JS_NewUCStringCopyNです。UNICODE版の文字列関数は、interned文字列用のものも提供されています。 As with other API calls, the names of Unicode-enabled API string functions correspond one-for-one with the standard engine API string function names as follows: if a standard function name is <code>JS_NewStringCopyN</code>, the corresponding Unicode version of the function is <code>JS_NewUCStringCopyN</code>. Unicode-enabled API string functions are also available for interned string.

Interned String Support

文字列格納用の領域を減らすために、JSエンジンは、違うときに使われる文字列を共有する仕組みがあります。 このような共有文字列のことを、"interned文字列"と呼びます。アプリケーション内で、1回以上特定の文字列が作られて、使われる場合には、 interned文字列を使ってください。 To save storage space, the JS engine provides support for sharing a single instance of a string among separate invocations. Such shared strings are called "interned strings". Use interned strings when you know that a particular, string of text will be created and used more than once in an application.

次のAPIにより、interned文字列を複数回にわたって使うことができます。 The engine API offers several calls for working with interned strings:

• JS_InternString, for creating or reusing a JSString.
• JS_InternUCString, for creating or reusing a Unicode JSString.
• JS_InternUCStringN, for creating or reusing Unicode JSString of fixed length.

Managing Security

JavaScript 1.3で、スクリプトをコンパイルする関数と、エンジンに渡されるスクリプトと関数を評価するための関数のセキュリティが強化されました。 JSのセキュリティモデルは、Javaのprincipals セキュリティモデルを基にしています。このモデルは、共通のセキュリティインターフェースを提供しますが、 実際の実装は、実装する人の責任です。 With JavaScript 1.3, the JS engine added security-enhanced API functions for compiling and evaluating scripts and functions passed to the engine. The JS security model is based on the Java principals security model. This model provides a common security interface, but the actual security implementation is up to you.

JavaScriptを実行できるアプリケーションで使われるセキュリティの方法の1つに、スクリプトの作成元を比較し、スクリプトの相互作用を場合によっては制限することが あります。例えば、アプリケーションで使う2つ以上のスクリプトの作成元を比較して、同じ作成元のスクリプトだけにスクリプトのプロパティの変更が 行えないようにすることができます。 One common way that security is used in a JavaScript-enabled application is to compare script origins and perhaps limit script interactions. For example, you might compare the codebase of two or more scripts in an application and only allow scripts from the same codebase to modify properties of scripts that share codebases.

セキュアなJSを実装するために、次のことを守って下さい。

To implement secure JS, follow these steps: <ol> <li>Declare one or more structs of type <code>JSPrincipals</code> in your application code.</li> <li>Implement the functions that will provide security information to the array. These include functions that provide an array of principals for your application, and mechanisms for incrementing and decrementing a reference count on the number of JS objects using a given set of principles.</li> <li>Populate the <code>JSPrincipals</code> struct with your security information. This information can include common codebase information.</li> <li>At run time, compile and evaluate all scripts and functions for which you intend to apply security using the JS API calls that require you to pass in a <code>JSPrincipals</code> struct. The following table lists these API functions and their purposes:</li> </ol>

1. アプリケーション内で、JSPrincipals型の構造体を定義します。
2. JSPrincipals構造体の構造体にセキュリティに関する情報を提供する関数を実装します。
3. 背キュウリ邸に関する情報を持つJSPrincipals構造体が利用できるようにします。この情報には、作成元に関する共通の情報を 格納できます。また、与えられたprincipalesのを使うオブジェクトの参照回数を増やしたり減らしたりするメカニズムを提供します。
4. 実行時に、JSPrincipals構造体を渡して実行する必要のあるAPIを呼ぶことで、セキュリティを適用するスクリプトや関数をコンパイルし実行して下さい。 次の表にこういったAPI関数をリストアップしました。