差分

このページの2つのバージョン間の差分を表示します。

--- translation:working:翻訳5 [2016-04-22 12:53]
Decomo
+++ translation:working:翻訳5 [2016-08-24 13:46] (現在)
Decomo
@@ 行 1: / 行 1: @@
-Using the File System Events API
+====== ファイルシステムイベントAPIを使う ======
-The File System Events API consists of several distinct groups of functions. You can obtain general information about volumes and events by using functions that begin with FSEvents. You can create a new event stream, perform operations on the stream, and so on using functions that begin with FSEventStream.
+ファイルシステムイベントAPIは、はっきりと異なる幾つかの機能グループからなります。
+''FSEvents''で始まる関数を使うことで、ボリュームとイベントに関する一般的な情報を取得できます。
+''FSEventStream''で始まる関数を使うことで、新規イベントストリームの作成、そのストリームにおける操作の実行などを行うことができます。
-The life cycle of a file system events stream is as follows:
+ファイルシステムイベントストリームのライフサイクルは下記の通りです：
-    The application creates a stream by calling FSEventStreamCreate or FSEventStreamCreateRelativeToDevice.
+  * アプリケーションが''FSEventStreamCreate''または''FSEventStreamCreateRelativeToDevice''を呼びストリームを作る。
+  * アプリケーションが''FSEventStreamScheduleWithRunLoop''を呼び、そのストリームのスケジュールを実行ループに組み込む。
+  * アプリケーションが''FSEventStreamStart''を呼び、ファイルシステムデーモンにイベント送信開始を伝える。
+  * アプリケーションが到着したイベントを処理する。APIは手順1で指定されたコールバック関数を呼び、イベントを投稿する。
+  * アプリケーションが''FSEventStreamStop''を呼び、デーモンにイベント送信停止を伝える。
+  * もしアプリケーションがストリームを再スタートする必要があれば、手順3へ飛ぶ。
+  * アプリケーションが''FSEventStreamUnscheduleFromRunLoop''を呼び、実行ループからのイベントスケジュールを取り除く。
+  * アプリケーションが''FSEventStreamInvalidate''を呼びストリームを無効化する。
+  * アプリケーションが''FSEventStreamRelease''を呼び、ストリームへの参照を開放する。
-    The application schedules the stream on the run loop by calling FSEventStreamScheduleWithRunLoop.
+以下の節で、これら手順をより詳しく解説します。
-    The application tells the file system events daemon to start sending events by calling FSEventStreamStart.
+===== include命令の追加 =====
-    The application services events as they arrive. The API posts events by calling the callback function specified in step 1.
+ファイルシステムイベントストリームAPIを使うには、次のようにCore Servicesフレームワークをインクルードしなければなりません：
-    The application tells the daemon to stop sending events by calling FSEventStreamStop.
-    If the application needs to restart the stream, go to step 3.
-    The application unschedules the event from its run loop by calling FSEventStreamUnscheduleFromRunLoop.
-    The application invalidates the stream by calling FSEventStreamInvalidate.
-    The application releases its reference to the stream by calling FSEventStreamRelease.
-These steps are explained in more detail in the sections that follow.
-Adding Include Directives
-Before you use the file system event stream API, you must include the Core Services framework as follows:
+<code c>
 #include <CoreServices/CoreServices.h>
+</code>
-When you compile, you must include the Core Services Framework by adding it to your target in Xcode or by adding the flag -framework CoreServices to your linker flags on the command line or in a Makefile.
+コンパイルの際、Core ServicesフレームワークをXcodeのターゲットに追加するか、コマンドラインまたは''Makefile''内のリンカフラグに''-framework CoreServices''フラグを追加しなければなりません。
-Creating an Event Stream
-The file system events API supports two types of event streams: per-disk event streams and a per-host event streams. Before you can create a stream, you must decide which type of stream to create: a per-host event stream or a per-disk event stream. You can create these streams by calling the functions FSEventStreamCreate and FSEventStreamCreateRelativeToDevice, respectively.
-A per-host event stream consists of events whose IDs are increasing with respect to other events on that host. These IDs are guaranteed to be unique with one exception: if additional disks are added from another computer that was also running OS X v10.5 or later, historical IDs may conflict between these volumes. Any new events will automatically start after the highest-numbered historical ID for any attached drive.
-A per-disk event stream, by contrast, consists of events whose IDs are increasing with respect to previous events on that disk. It does not have any relationship with other events on other disks, and thus you must create a separate event stream for each physical device that you wish to monitor.
-In general, if you are writing software that requires persistence, you should use per-disk streams to avoid any confusion due to ID conflicts. By contrast, per-host streams are most convenient if you are monitoring for changes in a directory or tree of directories during normal execution, such as watching a queue directory.
-Note: Because disks can be modified by computers running earlier versions of OS X (or potentially other operating systems), you should treat the events list as advisory rather than a definitive list of all changes to the volume. If a disk is modified by a computer running a previous version of OS X, the historical log is discarded.
-For example, backup software should still periodically perform a full sweep of any volume to ensure that no changes fall through the cracks.
-If you are monitoring files on the root file system, either stream mechanism will behave similarly.
-For example, the following snippet shows how to create an event stream:
-    /* Define variables and create a CFArray object containing
-       CFString objects containing paths to watch.
-     */
-    CFStringRef mypath = CFSTR("/path/to/scan");
-    CFArrayRef pathsToWatch = CFArrayCreate(NULL, (const void **)&mypath, 1, NULL);
-    void *callbackInfo = NULL; // could put stream-specific data here.
-    FSEventStreamRef stream;
-    CFAbsoluteTime latency = 3.0; /* Latency in seconds */
-    /* Create the stream, passing in a callback */
+===== イベントストリームの作成 =====
-    stream = FSEventStreamCreate(NULL,
+ファイルシステムイベントAPIは2種類のイベントストリームに対応します。ディスク毎のイベントストリームとホスト毎のイベントストリームです。
+ストリームを生成する前に、どちらのストリームタイプにするか決めなければなりません。
+''FSEventStreamCreate''関数と''FSEventStreamCreateRelativeToDevice''関数を呼ぶことで、それぞれのストリームを生成できます。
-        &myCallbackFunction,
+ホスト毎イベントストリームは、そのホストにおける他のイベントに関連して増加するIDで構成されます。
+IDは1つの例外を除いて一意であることが保証されます。OS X v10.5以降の別のマシンで使われていた複数のディスクが追加されると、それらボリューム間で履歴IDが衝突する可能性があります。
+新規イベントは、追加ディスクの履歴IDの最大値以降で自動的に開始されます。
-        callbackInfo,
+対照的に、ディスク毎イベントストリームは、そのディスクにおける以前のイベントに関連して増加するIDで構成されます。
+他のディスクの他のイベントとは一切関係せず、従って、個々の物理デバイスをモニターしたければ個別にイベントストリームを生成せねばなりません。
-        pathsToWatch,
+一般的に、永続性が要求されるソフトウェアを書いているならば、IDの衝突を避けるためにディスク毎ストリームを使うべきです。
+一方、ホスト毎ストリームは、キューディレクトリの監視といった、通常実行中のディレクトリやディレクトリツリー内の変更をモニタリングする場合に最も向いています。
-        kFSEventStreamEventIdSinceNow, /* Or a previous event ID */
+<note>
+以前のOS Xバージョン（または可能性として他のオペレーティングシステム）が稼動するコンピュータによってディスクは変更される事があるため、イベントリストはそのボリュームに対する全ての変更の確実なリストとしてではなく、<html><ruby><rb>目安</rb><rp>（</rp><rt>advisory</rt><rp>）</rp></ruby></html>として扱うべきです。
+前バージョンのOS Xが動いているマシンでディスクを変更した場合、変更ログは破棄されます。
+</note>
-        latency,
+例えば、バックアップソフトウェアは、変更の見落としがないことを確実にするために、定期的に全てのボリュームをフルスキャンするべきです。
-        kFSEventStreamCreateFlagNone /* Flags explained in reference */
+ルートファイルシステム上のファイルを監視する場合は、どちらのストリーム機構も同じような振る舞いをします。
-    );
+例として、以下の<html><ruby><rb>コード片</rb><rp>（</rp><rt>snippet</rt><rp>）</rp></ruby></html>はイベントストリームの生成方法を示します：
-Once you have created an event stream, you must schedule it on your application’s run loop. To do this, call FSEventStreamScheduleWithRunLoop, passing in the newly-created stream, a reference to your run loop, and a run loop mode. For more information about run loops, read Run Loops.
+<code c>
+/* 監視するパスのCFStringオブジェクトを含む
+   CFArrayオブジェクトの変数を定義し生成する。
+*/
+CFStringRef mypath = CFSTR("/path/to/scan");
+CFArrayRef pathsToWatch = CFArrayCreate(NULL, (const void **)&mypath, 1, NULL);
+void *callbackInfo = NULL; // ここでストリーム固有データを入れられる。
+FSEventStreamRef stream;
+CFAbsoluteTime latency = 3.0; /* レイテンシは秒数 */
-If you don’t already have a run loop, you will need to devote a thread to this task. After creating a thread using your API of choice, call CFRunLoopGetCurrent to allocate an initial run loop for that thread. Any future calls to CFRunLoopGetCurrent will return the same run loop.
+/* コールバックを渡してストリームを生成する */
+stream = FSEventStreamCreate(NULL,
+    &myCallbackFunction,
+    callbackInfo,
+    pathsToWatch,
+    kFSEventStreamEventIdSinceNow, /* もしくは以前のイベントID */
+    latency,
+    kFSEventStreamCreateFlagNone /* 関数リファレンスで説明されているフラグ */
+);
+</code>
-For example, the following snippet shows how to schedule a stream, called stream, on the current thread’s run loop (not yet running):
+イベントストリームを生成した時点で、それをアプリケーションの実行ループにスケジューリングすべきです。
+これを行うには、生成した新規ストリーム、実行ループ、実行ループモードを引数として''FSEventStreamScheduleWithRunLoop''を呼びます。
+実行ループに関する更なる情報は[[https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Multithreading/RunLoopManagement/RunLoopManagement.html|Run Loops]]をお読み下さい。
-    FSEventStreamRef stream;
+もし、まだ実行ループを持っていなければ、このタスクのためにスレッドを割り当てる必要があるでしょう。
+あなたが選択したAPIを使ってスレッドを生成した後は、そのスレッドに最初の実行ループを確保するために''CFRunLoopGetCurrent''を呼びます。
+以後''CFRunLoopGetCurrent''は、その同一の実行ループを返します。
-    /* Create the stream before calling this. */
+例として、以下の<html><ruby><rb>コード片</rb><rp>（</rp><rt>snippet</rt><rp>）</rp></ruby></html>はストリーム??stream??を現在のスレッドの（まだ実行していない）実行ループにスケジュールする方法を示します：
-    FSEventStreamScheduleWithRunLoop(stream, CFRunLoopGetCurrent(),         kCFRunLoopDefaultMode);
+<code c>
+FSEventStreamRef stream;
+/* 以下の関数を呼ぶ前にストリームを生成する。 */
+FSEventStreamScheduleWithRunLoop(stream, CFRunLoopGetCurrent(),         kCFRunLoopDefaultMode);
+</code>
-The final step in setting up an event stream is to call FSEventStreamStart. This function tells the event stream to begin sending events. Its sole parameter is the event stream to start.
+イベントストリーム設定の最終工程は''FSEventStreamStart''を呼ぶことです。
+この関数は、イベントストリームにイベントの送信開始を指示します。
+開始させるイベントストリームが唯一の引数です。
-Once the event stream has been created and scheduled, if your run loop is not already running, you should start it by calling CFRunLoopRun.
+イベントストリームの生成とスケジュールを行い、もしまだ実行ループを走らせていなければ、''CFRunLoopRun''を読んでそれを始動させましょう。
-Handling Events
-Your event handler callback must conform to the prototype for FSEventStreamCallback. The parameters are described in the reference documentation for the FSEventStreamCallback data type.
+===== イベントの取り扱い =====
-Your event handler receives three lists: a list of paths, a list of identifiers, and a list of flags. In effect, these represent a list of events. The first event consists of the first entry taken from each of the arrays, and so on. Your handler must iterate through these lists, processing the events as needed.
+イベントハンドラーコールバックは''FSEventStreamCallback''プロトタイプに適合していなければなりません。
+パラメータは''FSEventStreamCallback''データ型のリファレンスマニュアルで解説しています。
-For each event, you should scan the directory at the specified path, processing its contents as desired. Normally, you need to scan only the exact directory specified by the path. However, there are three situations in which this is not the case:
+イベントハンドラは、パス、識別子、フラグの3つのリストを受け取ります。
+実質的に、これらがイベントのリストを表します。
+The first event consists of the first entry taken from each of the arrays, and so on.
+イベント処理の必要に応じて、ハンドラはこれらリストをイテレートして下さい。
-    If an event in a directory occurs at about the same time as one or more events in a subdirectory of that directory, the events may be coalesced into a single event. In this case, you will receive an event with the kFSEventStreamEventFlagMustScanSubDirs flag set. When you receive such an event, you must recursively rescan the path listed in the event. The additional changes are not necessarily in an immediate child of the listed path.
+For each event, you should scan the directory at the specified path, processing its contents as desired.
+通常、そのパスによって示されるディレクトリだけを走査する必要があります。しかしながら、そのケースに当てはまらない3つの状況があります:
-    If a communication error occurs between the kernel and the user-space daemon, you may receive an event with either the kFSEventStreamEventFlagKernelDropped or kFSEventStreamEventFlagUserDropped flag set. In either case, you must do a full scan of any directories that you are monitoring because there is no way to determine what may have changed.
+  * １つのディレクトリにおいて、サブディレクトリ内で複数のイベントが同時に発生した場合、それらイベントは1つのイベントにまとめられる可能性があります。このケースでは、''kFSEventStreamEventFlagMustScanSubDirs''フラグが立ったイベントを受信することになります。このようなイベントを受信した時は、そのイベントに載っているパスを再帰的に再走査すべきです。変化の追加分は、必ずしもリストアップされたパスの直接の子供にあるとは限りません。
+  * カーネルとユーザー空間の間でコミュニケーションエラーが発生した場合、''kFSEventStreamEventFlagKernelDropped''か''kFSEventStreamEventFlagUserDropped''フラグが立ったイベントを受け取ることになるでしょう。このケースでは、監視中の全てのディレクトリをフルスキャンしなければなりません。なぜならば、何が変更されたかを決める一切の手立てがないからです。
+<note>
+イベントのドロップ時は''kFSEventStreamEventFlagMustScanSubDirs''フラグも同様にセットされます。
+上で述べたように、パスのフルスキャンを行うべきかどうかの判断では、
     Note: When an event is dropped, the kFSEventStreamEventFlagMustScanSubDirs flag is also set. Thus, it is not necessary to explicitly check for the dropped event flags when determining whether to perform a full rescan of a path. The dropped event flags are provided purely for informational purposes.