FileStream オブジェクトの position プロパティ

Adobe AIR 1.0 およびそれ以降

FileStream オブジェクトの position プロパティでは、次の読み取りまたは書き込みメソッドでデータの読み取りまたは書き込みを行う位置を指定します。

読み取りまたは書き込み操作の前に、 position プロパティにファイル内の任意の有効な位置を設定します。

例えば、次のコードでは、ファイル内の位置 8 にストリング「 hello 」を（UTF エンコード形式で）書き込みます。

var myFile = air.File.documentsDirectory; 
myFile = myFile.resolvePath("AIR Test/test.txt"); 
var myFileStream = new air.FileStream(); 
myFileStream.open(myFile, air.FileMode.UPDATE); 
myFileStream.position = 8; 
myFileStream.writeUTFBytes("hello");

最初に FileStream オブジェクトを開いたときは、 position プロパティは 0 に設定されています。

読み取り操作を行う場合はその操作の前に、 position の値が 0 以上で、かつファイルのバイト数より小さい値（ファイル内に存在する位置）に設定されている必要があります。

position プロパティの値は、次の場合にのみ変更されます。

position プロパティを明示的に設定したとき
読み取りメソッドを呼び出したとき
書き込みメソッドを呼び出したとき

FileStream オブジェクトの読み取りまたは書き込みメソッドを呼び出すと、すぐに position プロパティの値が、読み取りまたは書き込みを行ったバイト数だけインクリメントされます。使用する読み取りメソッドによって、 position プロパティの値が、指定された読み取り対象のバイト数だけインクリメントされる場合と、使用できるバイト数だけインクリメントされる場合があります。その後に読み取りまたは書き込みメソッドを呼び出すと、その新しい位置から読み取りまたは書き込みが開始されます。

var myFile = air.File.documentsDirectory; 
myFile = myFile.resolvePath("AIR Test/test.txt"); 
var myFileStream = new air.FileStream(); 
myFileStream.open(myFile, air.FileMode.UPDATE); 
myFileStream.position = 4000; 
alert(myFileStream.position);  // 4000 
myFileStream.writeBytes(myByteArray, 0, 200); 
alert(myFileStream.position); // 4200

ただし 1 つ例外があり、追加モードで開いた FileStream では、書き込みメソッドの呼び出し後に position プロパティは変更されません（追加モードでは、 position プロパティの値に関係なく、常にファイルの末尾にデータが書き込まれます）。

非同期操作用に開いたファイルでは、次のコード行が実行されるまで書き込み操作は実行されません。ただし、複数の非同期メソッドを連続して呼び出すことは可能で、その場合はランタイムによって順番に実行されます。

var myFile = air.File.documentsDirectory; 
myFile = myFile.resolvePath("AIR Test/test.txt"); 
var myFileStream = new air.FileStream(); 
myFileStream.openAsync(myFile, air.FileMode.WRITE); 
myFileStream.writeUTFBytes("hello"); 
myFileStream.writeUTFBytes("world"); 
myFileStream.addEventListener(air.Event.CLOSE, closeHandler); 
myFileStream.close(); 
air.trace("started."); 
 
closeHandler(event) 
{ 
    air.trace("finished."); 
}

このコードのトレース出力は次のようになります。

started. 
finished.

position の値は、読み取りまたは書き込みメソッドを呼び出した後すぐに（いつでも）指定できます。次の読み取りまたは書き込み操作は、その位置から開始されます。例えば、次のコードでは、 writeBytes() メソッドを呼び出した直後に position プロパティを設定しています。書き込み操作の完了後も、 position はその値（300）に設定されています。

var myFile = air.File.documentsDirectory.resolvePath("AIR Test/test.txt"); 
var myFileStream = new air.FileStream(); 
myFileStream.openAsync(myFile, air.FileMode.UPDATE); 
myFileStream.position = 4000; 
air.trace(myFileStream.position); // 4000 
myFileStream.writeBytes(myByteArray, 0, 200); 
myFileStream.position = 300; 
air.trace(myFileStream.position); // 300