<Return[C]><Top>

CreateFile

Declare Function Api_CreateFile& Lib "kernel32" Alias "CreateFileA" (ByVal lpFileName$, ByVal dwDesiredAccess&, ByVal dwShareMode&, lpSecurityAttributes As Any, ByVal dwCreationDisposition&, ByVal dwFlagsAndAttributes&, ByVal hTemplateFile&)

Declare Function CreateFile Lib "kernel32" Alias "CreateFileA" (ByVal lpFileName As String, ByVal dwDesiredAccess As Long, ByVal dwShareMode As Long, lpSecurityAttributes As SECURITY_ATTRIBUTES, ByVal dwCreationDisposition As Long, ByVal dwFlagsAndAttributes As Long, ByVal hTemplateFile As Long) As Long

次のオブジェクトを作成するか開き、そのオブジェクトをアクセスするために利用できるハンドルを返す。
コンソール・通信リソース・ディレクトリ(開くだけで作成は不可能)・ディスクデバイス(Windows NT/2000 )・ファイル・メールスロット・パイプ

パラメータ
lpFileName
    作成または開く対象のオブジェクトの名前を保持している、NULL で終わる文字列へのポインタを指定する。
    Windows NT/2000:この関数の ANSI 版では、名前は最大 MAX_PATH 文字に制限されている。

    この制限をほぼ 32,000 ワイド文字へ拡張するには、この関数の Unicode 版を呼び出し、パスの前に "\\?\" という接頭辞を追加する。

    Windows 95/98:文字列の長さは、最大 MAX_PATH 文字である。
dwDesiredAccess
    オブジェクトへのアクセスのタイプを指定する。アプリケーションは、読み取りアクセス、書き込みアクセス、読み書きアクセス、デバイス問い

    合わせアクセスのいずれかを取得できる。次の値の任意の組み合わせを指定する。

    値                            

意味                                                                                                                                 

    0

オブジェクトへのデバイス問い合わせアクセスを指定する。

 

アプリケーションは、デバイスにアクセスすることなく、デバイス属性の問い合わせを行える。

    GENERIC_READ

オブジェクトへの読み取りアクセスを指定する。データの読み取りとファイルポインタの移動ができる。

 

読み書きアクセスを行うには、GENERIC_WRITE と共に指定する。

    GENERIC_WRITE

オブジェクトへの書き込みアクセスを指定する。データの書き込みとファイルポインタの移動ができる。

 

読み書きアクセスを行うには、GENERIC_READ と共に指定する。

    また、次のアクセスフラグを指定することもできる。

    Value値                                            

参照個所                                                     

    DELETE

MSDN ライブラリの「Standard Access Rights」

    READ_CONTROL

MSDN ライブラリの「Standard Access Rights」

    WRITE_DAC

MSDN ライブラリの「Standard Access Rights」

    WRITE_OWNER

MSDN ライブラリの「Standard Access Rights」

    SYNCHRONIZE

MSDN ライブラリの「Standard Access Rights」

    STANDARD_RIGHTS_REQUIRED

MSDN ライブラリの「Standard Access Rights」

    STANDARD_RIGHTS_READ

MSDN ライブラリの「Standard Access Rights」

    STANDARD_RIGHTS_WRITE

MSDN ライブラリの「Standard Access Rights」

    STANDARD_RIGHTS_EXECUTE

MSDN ライブラリの「Standard Access Rights」

    STANDARD_RIGHTS_ALL

MSDN ライブラリの「Standard Access Rights」

    SPECIFIC_RIGHTS_ALL

ACCESS_MASK 構造体

    ACCESS_SYSTEM_SECURITY

ACCESS_MASK 構造体

    MAXIMUM_ALLOWED

ACCESS_MASK 構造体

    GENERIC_READ

ACCESS_MASK 構造体

    GENERIC_WRITE

ACCESS_MASK 構造体

    GENERIC_EXECUTE

ACCESS_MASK 構造体

    GENERIC_ALL

ACCESS_MASK 構造体

dwShareMode
    オブジェクトの共有方法を指定する。0 を指定すると、オブジェクトを共有できない。

    このハンドルを閉じない限り、それ以降にこのオブジェクトを開こうとしても失敗する。
    オブジェクトを共有するには、次の値のいずれかまたは任意の組み合わせを指定する。

    値                                  

意味                                                                                                                                   

    FILE_SHARE_DELETE

Windows NT/2000:これ以降、オブジェクトを開こうとしたときに削除アクセスを要求した場合のみ、その操作

 

を許可する。

    FILE_SHARE_READ

これ以降、オブジェクトを開こうとしたときに読み取りアクセスを要求した場合のみ、その操作を許可する。

    FILE_SHARE_WRITE

これ以降、オブジェクトを開こうとしたときに書き込みアクセスを要求した場合のみ、その操作を許可する。

lpSecurityAttributes
    取得したハンドルを子プロセスへ継承することを許可するかどうかを決定する、1 個の SECURITY_ATTRIBUTES 構造体へのポインタを

    指定する。NULL を指定すると、そのハンドルは継承できない。
    Windows NT/2000:この構造体の lpSecurityDescriptor メンバでセキュリティ記述子を設定する。

    lpSecurityAttributes パラメータで NULL を指定すると、既定のセキュリティ記述子が適用される。

    このパラメータを有効にするには、作成先のファイルシステムがファイルとディレクトリのセキュリティをサポートしていなければならない。
dwCreationDisposition
    ファイルが存在する場合、または存在しない場合のファイルの扱い方を指定する。

    このパラメータには、次の値のいずれかを指定しなければならない。

    値                            

意味                                                                                                                          

    CREATE_NEW

新しいファイルを作成する。指定したファイルが既に存在している場合、この関数は失敗する。

    CREATE_ALWAYS

新しいファイルを作成する。指定したファイルが既に存在している場合、そのファイルを上書きし、既存の属性を

 

消去する。

    OPEN_EXISTING

ファイルを開く。指定したファイルが存在していない場合、この関数は失敗する。

    OPEN_ALWAYS ファイルが存在している場合、そのファイルを開く。指定したファイルが存在していない場合、この関数は

    dwCreationDisposition パラメータで CREATE_NEW が指定されていたと仮定して新しいファイルを作成する。
    TRUNCATE_EXISTING ファイルを開き、ファイルのサイズを 0 バイトにする。呼び出し側プロセスは、dwDesiredAccess パラメータで、

    少なくとも GENERIC_WRITE アクセス権を指定しなければならない。指定したファイルが存在していない場合、この関数は失敗する。
dwFlagsAndAttributes
    ファイルの属性とフラグを指定する。
    属性は、次の属性の任意の組み合わせを指定する。ただし、FILE_ATTRIBUTE_NORMAL は単独で指定する。

    FILE_ATTRIBUTE_NORMAL と他の属性のいずれかを共に指定すると、FILE_ATTRIBUTE_NORMAL は無効になる。

    属性                                                  

意味                                                                                                                

    FILE_ATTRIBUTE_ARCHIVE

このファイルをアーカイブするべきである。アプリケーションはこの属性を、ファイルのバックアップや

 

削除のためのマークとして使う。

    FILE_ATTRIBUTE_ENCRYPTED

このファイルまたはディレクトリを暗号化するよう指示する。ファイルに対して指定した場合、そのファ

 

イル内のすべてのデータを暗号化することを意味する。

 

ディレクトリに対して指示した場合、その中に新しく作成されるファイルとサブディレクトリに対して、

 

既定で暗号化を行うことを意味する。

 

FILE_ATTRIBUTE_SYSTEM と共に指定すると、FILE_ATTRIBUTE_ENCRYPTED フラグ

 

は無効になる。

    FILE_ATTRIBUTE_HIDDEN

このファイルは隠しファイルである。通常のディレクトリリスティングでは表示されない。

    FILE_ATTRIBUTE_NORMAL

このファイルに特に属性を設定しない。単独で指定した場合にのみ、この属性は有効である。

    FILE_ATTRIBUTE_NOT

                    _CONTENT_INDEXED

Windows 2000:このファイルを、「インデックスサービス」の対象にしない。

    FILE_ATTRIBUTE_OFFLINE

Windows 2000:このファイルのデータは、すぐには利用できない。

 

この属性は、このファイルのデータがオフライン記憶装置へ物理的に移動されたことを示す。

 

この属性は、Windows 2000 の階層記憶管理ソフトウェアである「リモート記憶域」が利用する

 

ものである。アプリケーションは、任意にこの属性を変更するべきではない。

    FILE_ATTRIBUTE_READONLY

 このファイルは読み取り専用である。アプリケーションはこのファイルの読み取りを行えるが、書き

 

込みや削除はできない。

   FILE_ATTRIBUTE_SYSTEM 

このファイルは、オペレーティングシステムの一部、またはオペレーティングシステム専用のファイル

 

である。

    FILE_ATTRIBUTE_TEMPORARY

このファイルは、一時ファイルとして使われています。ファイルシステムは、データをハードディスク

 

のような大容量記憶装置へ書き込む代わりに、高速なアクセスが行えるよう、すべてのデータを

 

メモリ内に維持することを試みる。アプリケーションは、必要がなくなった段階で一時ファイルをすぐ

 

に削除するべきである。

    dwFlagsAndAttributes パラメータでは、次のフラグの任意の組み合わせを指定する。

    フラグ                                               

意味                                                                                                            

    FILE_FLAG_WRITE_THROUGH

キャッシュに書き込まれたデータを直接ディスクに書き込むようシステムに指示する。

 

システムは依然としてキャッシュ書き込み操作を行えるが、ディスクへの遅延書き込みは無効に

 

なる。

    FILE_FLAG_OVERLAPPED

オブジェクトを初期化するようシステムに指示する。その結果、非常に長い時間のかかる処理に対

 

して ERROR_IO_PENDING が返るようになる。この処理が終了すると、指定されたイベントは、

 

シグナル状態に設定される。

 

このフラグを指定したときは、ファイルの読み書きを行う関数で 1 個の OVERLAPPED 構造体を

 

指定しなければならない。つまり、FILE_FLAG_OVERLAPPED を指定した場合、アプリケーシ

 

ョンはオーバーラップ読み書きを行わなければならない。

 

FILE_FLAG_OVERLAPPED を指定した場合、システムはファイルポインタを管理しない。

 

ファイルの読み書きを行う関数に対し、1 個の OVERLAPPED 構造体を指している lpOverlapped

 

パラメータの一部として、ファイルの位置を渡さなければならない。

 

また、このフラグを指定した場合、1 つのハンドルに対して複数の操作(たとえば、読み取りと書

 

き込みそれぞれの操作)を同時に行うことができる。

    FILE_FLAG_NO_BUFFERING

バッファやキャッシュを使わずにファイルを開くようシステムに指示する。

 

FILE_FLAG_OVERLAPPED フラグと共に指定すると、非同期操作のパフォーマンスが向上す

 

る。I/O 操作を行う際に、メモリマネージャの同期処理に依存する必要がなくなるからである。

 

しかし、データがキャッシュ内に存在しないので、一部の I/O 操作には多くの時間がかかる。

 

このフラグを指定した場合、アプリケーションは次の各条件を満たさなければならない。

    FILE_FLAG_RANDOM_ACCESS

このファイルをランダムアクセスすることをシステムに指示する。

 

システムは、この指定をファイルのキャッシングを最適化するためのヒントとして使う。

    FILE_FLAG_SEQUENTIAL_SCAN

ファイルを最初から最後までシーケンシャルに(連続)アクセスすることをシステムに指示する。

 

システムは、この指定をファイルのキャッシングを最適化するためのヒントとして使う。

 

この場合、アプリケーションはランダムアクセスを行う目的でファイルポインタを移動することはできる

 

が、最適なキャッシングが達成できなくなる可能性がある。しかし、ランダムアクセスを正しく行え

 

ることは保証されている。

    FILE_FLAG_BACKUP_SEMANTICS

Windows NT/2000:バックアップまたは復元操作の目的で、ファイルを開くまたは作成するようシ

 

ステムに指示する。呼び出し側プロセスがファイルセキュリティに関して十分な権限を備えているこ

 

とを前提として、システムは、そのプロセスがファイルセキュリティのチェックを無効にできることを保

 

証する。これに関連する権限は、SE_BACKUP_NAME と SE_RESTORE_NAME である。

    FILE_FLAG_POSIX_SEMANTICS

POSIX(UNIX ベースのポータブル OS)の規則に従ってファイルにアクセスするようシステムに指

 

示する。この規則には、ファイル名が同じで大文字と小文字だけが異なる複数のファイルを認める

 

ファイルシステムに対し、それらのファイルへのアクセスを認めることが含まれる。

    CreateFile 関数が名前付きパイプのクライアント側を開く場合、dwFlagsAndAttributes パラメータでセキュリティのサービス品質(Security

    Quality of Service)情報を指定できる。呼び出し側アプリケーションが SECURITY_SQOS_PRESENT フラグを指定している場合、

    dwFlagsAndAttributes パラメータには、次の値のいずれかまたは任意の組み合わせを指定できる。

    値                                                    

意味                                                                                                        

    SECURITY_ANONYMOUS

名前なし(Anonymous)偽装レベルでクライアントを偽装するよう指定する。

    SECURITY_IDENTIFICATION

識別(Identification)偽装レベルでクライアントを偽装するよう指定する。

    SECURITY_IMPERSONATION

偽装(Impersonation)偽装レベルでクライアントを偽装するよう指定する。

    SECURITY_DELEGATION 代理

(Delegation)偽装レベルでクライアントを偽装するよう指定する。

    SECURITY_CONTEXT_TRACKING

セキュリティ追跡モードが動的であることを指定する。

 

このフラグを指定しない場合、セキュリティ追跡モードは静的である。

    SECURITY_EFFECTIVE_ONLY

クライアントのセキュリティコンテキストのうち、有効になっている部分だけをサーバーで利用できるよ

 

うにする。このフラグを指定しない場合は、すべての部分が利用できる。

 

このフラグを指定すると、クライアントは、サーバーがクライアントを偽装する際に利用できるグループ

 

と権限を制限できる。

    SECURITY_SQOS_PRESENT

クライアントが CreateFile 関数を使ってパイプのクライアント側のハンドルを開く際に、サーバーの偽

 

装レベルを指定する。

hTemplateFile
    テンプレートファイルに対して GENERIC_READ アクセス権を備えているハンドルを指定する。

    テンプレートファイルは、作成対象のファイルに対して、ファイル属性と拡張属性を提供する。
    Windows 95:NULL を指定する。何かハンドルを指定すると、この関数は失敗し、GetLastError は ERROR_NOT_SUPPORTED を

    返す。

戻り値
    関数が成功すると、指定したファイルに対する、開いているハンドルが返る。

    dwCreationDistribution パラメータで CREATE_ALWAYS または OPEN_ALWAYS を指定し、lpFileName パラメータで指定したファイル

    が既に存在している場合、(CreateFile が成功した場合でも)GetLastError 関数は ERROR_ALREADY_EXISTS を返す。

    CreateFile を実行する前にファイルが存在していない場合、GetLastError は 0 を返す。
    関数が失敗すると、INVALID_HANDLE_VALUE が返る。拡張エラー情報を取得するには、GetLastError 関数を使う。