Win32 API 日本語リファレンス
ホームSystem.Com.StructuredStorage › StgCreateDocfile

StgCreateDocfile

関数
新しい複合ドキュメントファイルを作成しルートストレージを開く。
DLLOLE32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// OLE32.dll
#include <windows.h>

HRESULT StgCreateDocfile(
    LPCWSTR pwcsName,   // optional
    STGM grfMode,
    DWORD reserved,   // optional
    IStorage** ppstgOpen
);

パラメーター

名前方向説明
pwcsNameLPCWSTRinoptional作成する複合ファイルの名前を表す、null で終わる Unicode 文字列へのポインター。この文字列は解釈されずにファイル システムへ渡されます。相対名または NULL を指定できます。NULL の場合、一意の名前を持つ一時的な複合ファイルが割り当てられます。
grfModeSTGMin新しいストレージ オブジェクトを開くときに使用するアクセス モードを指定します。詳細については、STGM Constants を参照してください。呼び出し元が STGM_CREATE または STGM_CONVERT と共にトランザクション モードを指定した場合、上書きまたは変換は、ルート ストレージに対してコミット操作が呼び出された時点で実行されます。ルート ストレージ オブジェクトに対して IStorage::Commit が呼び出されない場合、ファイルの以前の内容が復元されます。トランザクション モードでファイルを上書きまたは変換する際にはスナップショット コピーが必要になるため、STGM_CREATE および STGM_CONVERTSTGM_NOSNAPSHOT フラグと組み合わせることはできません。
reservedDWORDoptional将来の使用のために予約されています。0 を指定する必要があります。
ppstgOpenIStorage**out新しいストレージ オブジェクトの IStorage ポインターを格納する場所へのポインター。

戻り値の型: HRESULT

公式ドキュメント

IStorage インターフェイスの COM 提供による複合ファイル実装を使用して、新しい複合ファイル ストレージ オブジェクトを作成します。

戻り値

StgCreateDocfile は、HRESULT にラップされたファイル システム エラーやシステム エラーを返すこともあります。詳細については、 Error Handling Strategies および Handling Unknown Errors を参照してください。

解説(Remarks)

StgCreateDocfile 関数は、 IStorage インターフェイスの COM 提供による複合ファイル実装を使用して、新しいストレージ オブジェクトを作成します。開いている複合ファイルの名前は、 IStorage::Stat メソッドを呼び出すことで取得できます。

StgCreateDocfile は、ファイルが存在しない場合はファイルを作成します。ファイルが既に存在する場合は、grfMode パラメーターで指定する STGM_CREATESTGM_CONVERTSTGM_FAILIFTHERE の各フラグによって動作が決まります。詳細については、STGM Constants を参照してください。

複合ファイルがトランザクション モード (grfMode パラメーターに STGM_TRANSACTED を指定) で開かれ、同じ名前のファイルが既に存在する場合、未処理の変更がすべてコミットされるまで既存のファイルは変更されません。ファイル システムのアクセス制御により呼び出し側プロセスが既存のファイルへの書き込みアクセス権を持たない場合、grfMode パラメーターには STGM_READ のみを指定でき、STGM_WRITESTGM_READWRITE は指定できません。この場合でも、開かれた新しい複合ファイルへの書き込みは可能ですが、後続のコミット操作は失敗します (トランザクション モードでは、書き込み権限はコミット時に強制されます)。

STGM_SIMPLE を指定すると、機能は限定されるものの頻繁に使用されるケースにおいて、はるかに高速な複合ファイル オブジェクトの実装が提供されます。これは、複数のストリームを持ちストレージを持たない複合ファイル実装を必要とするアプリケーションで使用できます。シンプル モードは IStorage のすべてのメソッドをサポートするわけではありません。詳細については、STGM Constants を参照してください。

grfMode パラメーターに STGM_TRANSACTED が指定されており、pwcsName パラメーターで指定された名前のファイルがまだ存在しない場合、ファイルは直ちに作成されます。アクセス制御されたファイル システムでは、呼び出し元は複合ファイルが作成されるファイル システム上のディレクトリに対する書き込み権限を持っている必要があります。STGM_TRANSACTED が指定されず、STGM_CREATE が指定された場合は、同じ名前の既存のファイルが破棄された後に新しいファイルが作成されます。

StgCreateDocfile は、pwcsName パラメーターに NULL を渡すことで一時的な複合ファイルを作成するために使用できます。ただし、これらのファイルが一時的であるのは、システムによって付与される一意の名前 (多くの場合、ユーザーにとって意味を持たない名前) を持つという意味においてのみです。grfMode パラメーターに STGM_DELETEONRELEASE が指定されていない限り、一時ファイルの使用を終えた時点でそのファイルを削除する責任は呼び出し元にあります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// OLE32.dll
#include <windows.h>

HRESULT StgCreateDocfile(
    LPCWSTR pwcsName,   // optional
    STGM grfMode,
    DWORD reserved,   // optional
    IStorage** ppstgOpen
);
[DllImport("OLE32.dll", ExactSpelling = true)]
static extern int StgCreateDocfile(
    [MarshalAs(UnmanagedType.LPWStr)] string pwcsName,   // LPCWSTR optional
    uint grfMode,   // STGM
    uint reserved,   // DWORD optional
    IntPtr ppstgOpen   // IStorage** out
);
<DllImport("OLE32.dll", ExactSpelling:=True)>
Public Shared Function StgCreateDocfile(
    <MarshalAs(UnmanagedType.LPWStr)> pwcsName As String,   ' LPCWSTR optional
    grfMode As UInteger,   ' STGM
    reserved As UInteger,   ' DWORD optional
    ppstgOpen As IntPtr   ' IStorage** out
) As Integer
End Function
' pwcsName : LPCWSTR optional
' grfMode : STGM
' reserved : DWORD optional
' ppstgOpen : IStorage** out
Declare PtrSafe Function StgCreateDocfile Lib "ole32" ( _
    ByVal pwcsName As LongPtr, _
    ByVal grfMode As Long, _
    ByVal reserved As Long, _
    ByVal ppstgOpen As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

StgCreateDocfile = ctypes.windll.ole32.StgCreateDocfile
StgCreateDocfile.restype = ctypes.c_int
StgCreateDocfile.argtypes = [
    wintypes.LPCWSTR,  # pwcsName : LPCWSTR optional
    wintypes.DWORD,  # grfMode : STGM
    wintypes.DWORD,  # reserved : DWORD optional
    ctypes.c_void_p,  # ppstgOpen : IStorage** out
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLE32.dll')
StgCreateDocfile = Fiddle::Function.new(
  lib['StgCreateDocfile'],
  [
    Fiddle::TYPE_VOIDP,  # pwcsName : LPCWSTR optional
    -Fiddle::TYPE_INT,  # grfMode : STGM
    -Fiddle::TYPE_INT,  # reserved : DWORD optional
    Fiddle::TYPE_VOIDP,  # ppstgOpen : IStorage** out
  ],
  Fiddle::TYPE_INT)
#[link(name = "ole32")]
extern "system" {
    fn StgCreateDocfile(
        pwcsName: *const u16,  // LPCWSTR optional
        grfMode: u32,  // STGM
        reserved: u32,  // DWORD optional
        ppstgOpen: *mut *mut core::ffi::c_void  // IStorage** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("OLE32.dll")]
public static extern int StgCreateDocfile([MarshalAs(UnmanagedType.LPWStr)] string pwcsName, uint grfMode, uint reserved, IntPtr ppstgOpen);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLE32_StgCreateDocfile' -Namespace Win32 -PassThru
# $api::StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen)
#uselib "OLE32.dll"
#func global StgCreateDocfile "StgCreateDocfile" sptr, sptr, sptr, sptr
; StgCreateDocfile pwcsName, grfMode, reserved, ppstgOpen   ; 戻り値は stat
; pwcsName : LPCWSTR optional -> "sptr"
; grfMode : STGM -> "sptr"
; reserved : DWORD optional -> "sptr"
; ppstgOpen : IStorage** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
#uselib "OLE32.dll"
#cfunc global StgCreateDocfile "StgCreateDocfile" wstr, int, int, sptr
; res = StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen)
; pwcsName : LPCWSTR optional -> "wstr"
; grfMode : STGM -> "int"
; reserved : DWORD optional -> "int"
; ppstgOpen : IStorage** out -> "sptr"
; HRESULT StgCreateDocfile(LPCWSTR pwcsName, STGM grfMode, DWORD reserved, IStorage** ppstgOpen)
#uselib "OLE32.dll"
#cfunc global StgCreateDocfile "StgCreateDocfile" wstr, int, int, intptr
; res = StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen)
; pwcsName : LPCWSTR optional -> "wstr"
; grfMode : STGM -> "int"
; reserved : DWORD optional -> "int"
; ppstgOpen : IStorage** out -> "intptr"
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	ole32 = windows.NewLazySystemDLL("OLE32.dll")
	procStgCreateDocfile = ole32.NewProc("StgCreateDocfile")
)

// pwcsName (LPCWSTR optional), grfMode (STGM), reserved (DWORD optional), ppstgOpen (IStorage** out)
r1, _, err := procStgCreateDocfile.Call(
	uintptr(unsafe.Pointer(windows.StringToUTF16Ptr(pwcsName))),
	uintptr(grfMode),
	uintptr(reserved),
	uintptr(ppstgOpen),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // HRESULT
function StgCreateDocfile(
  pwcsName: PWideChar;   // LPCWSTR optional
  grfMode: DWORD;   // STGM
  reserved: DWORD;   // DWORD optional
  ppstgOpen: Pointer   // IStorage** out
): Integer; stdcall;
  external 'OLE32.dll' name 'StgCreateDocfile';
result := DllCall("OLE32\StgCreateDocfile"
    , "WStr", pwcsName   ; LPCWSTR optional
    , "UInt", grfMode   ; STGM
    , "UInt", reserved   ; DWORD optional
    , "Ptr", ppstgOpen   ; IStorage** out
    , "Int")   ; return: HRESULT
●StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen) = DLL("OLE32.dll", "int StgCreateDocfile(char*, dword, dword, void*)")
# 呼び出し: StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen)
# pwcsName : LPCWSTR optional -> "char*"
# grfMode : STGM -> "dword"
# reserved : DWORD optional -> "dword"
# ppstgOpen : IStorage** out -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "ole32" fn StgCreateDocfile(
    pwcsName: [*c]const u16, // LPCWSTR optional
    grfMode: u32, // STGM
    reserved: u32, // DWORD optional
    ppstgOpen: ?*anyopaque // IStorage** out
) callconv(std.os.windows.WINAPI) i32;
proc StgCreateDocfile(
    pwcsName: WideCString,  # LPCWSTR optional
    grfMode: uint32,  # STGM
    reserved: uint32,  # DWORD optional
    ppstgOpen: pointer  # IStorage** out
): int32 {.importc: "StgCreateDocfile", stdcall, dynlib: "OLE32.dll".}
pragma(lib, "ole32");
extern(Windows)
int StgCreateDocfile(
    const(wchar)* pwcsName,   // LPCWSTR optional
    uint grfMode,   // STGM
    uint reserved,   // DWORD optional
    void* ppstgOpen   // IStorage** out
);
ccall((:StgCreateDocfile, "OLE32.dll"), stdcall, Int32,
      (Cwstring, UInt32, UInt32, Ptr{Cvoid}),
      pwcsName, grfMode, reserved, ppstgOpen)
# pwcsName : LPCWSTR optional -> Cwstring
# grfMode : STGM -> UInt32
# reserved : DWORD optional -> UInt32
# ppstgOpen : IStorage** out -> Ptr{Cvoid}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int32_t StgCreateDocfile(
    const uint16_t* pwcsName,
    uint32_t grfMode,
    uint32_t reserved,
    void* ppstgOpen);
]]
local ole32 = ffi.load("ole32")
-- ole32.StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen)
-- pwcsName : LPCWSTR optional
-- grfMode : STGM
-- reserved : DWORD optional
-- ppstgOpen : IStorage** out
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('OLE32.dll');
const StgCreateDocfile = lib.func('__stdcall', 'StgCreateDocfile', 'int32_t', ['str16', 'uint32_t', 'uint32_t', 'void *']);
// StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen)
// pwcsName : LPCWSTR optional -> 'str16'
// grfMode : STGM -> 'uint32_t'
// reserved : DWORD optional -> 'uint32_t'
// ppstgOpen : IStorage** out -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("OLE32.dll", {
  StgCreateDocfile: { parameters: ["buffer", "u32", "u32", "pointer"], result: "i32" },
});
// lib.symbols.StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen)
// pwcsName : LPCWSTR optional -> "buffer"
// grfMode : STGM -> "u32"
// reserved : DWORD optional -> "u32"
// ppstgOpen : IStorage** out -> "pointer"
// 文字列引数は "buffer"(NUL 終端のバイト列を Uint8Array で渡す)。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t StgCreateDocfile(
    const uint16_t* pwcsName,
    uint32_t grfMode,
    uint32_t reserved,
    void* ppstgOpen);
C, "OLE32.dll");
// $ffi->StgCreateDocfile(pwcsName, grfMode, reserved, ppstgOpen);
// pwcsName : LPCWSTR optional
// grfMode : STGM
// reserved : DWORD optional
// ppstgOpen : IStorage** out
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Ole32 extends StdCallLibrary {
    Ole32 INSTANCE = Native.load("ole32", Ole32.class);
    int StgCreateDocfile(
        WString pwcsName,   // LPCWSTR optional
        int grfMode,   // STGM
        int reserved,   // DWORD optional
        Pointer ppstgOpen   // IStorage** out
    );
}
@[Link("ole32")]
lib LibOLE32
  fun StgCreateDocfile = StgCreateDocfile(
    pwcsName : UInt16*,   # LPCWSTR optional
    grfMode : UInt32,   # STGM
    reserved : UInt32,   # DWORD optional
    ppstgOpen : Void*   # IStorage** out
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef StgCreateDocfileNative = Int32 Function(Pointer<Utf16>, Uint32, Uint32, Pointer<Void>);
typedef StgCreateDocfileDart = int Function(Pointer<Utf16>, int, int, Pointer<Void>);
final StgCreateDocfile = DynamicLibrary.open('OLE32.dll')
    .lookupFunction<StgCreateDocfileNative, StgCreateDocfileDart>('StgCreateDocfile');
// pwcsName : LPCWSTR optional -> Pointer<Utf16>
// grfMode : STGM -> Uint32
// reserved : DWORD optional -> Uint32
// ppstgOpen : IStorage** out -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function StgCreateDocfile(
  pwcsName: PWideChar;   // LPCWSTR optional
  grfMode: DWORD;   // STGM
  reserved: DWORD;   // DWORD optional
  ppstgOpen: Pointer   // IStorage** out
): Integer; stdcall;
  external 'OLE32.dll' name 'StgCreateDocfile';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "StgCreateDocfile"
  c_StgCreateDocfile :: CWString -> Word32 -> Word32 -> Ptr () -> IO Int32
-- pwcsName : LPCWSTR optional -> CWString
-- grfMode : STGM -> Word32
-- reserved : DWORD optional -> Word32
-- ppstgOpen : IStorage** out -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let stgcreatedocfile =
  foreign "StgCreateDocfile"
    ((ptr uint16_t) @-> uint32_t @-> uint32_t @-> (ptr void) @-> returning int32_t)
(* pwcsName : LPCWSTR optional -> (ptr uint16_t) *)
(* grfMode : STGM -> uint32_t *)
(* reserved : DWORD optional -> uint32_t *)
(* ppstgOpen : IStorage** out -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library ole32 (t "OLE32.dll"))
(cffi:use-foreign-library ole32)

(cffi:defcfun ("StgCreateDocfile" stg-create-docfile :convention :stdcall) :int32
  (pwcs-name (:string :encoding :utf-16le))   ; LPCWSTR optional
  (grf-mode :uint32)   ; STGM
  (reserved :uint32)   ; DWORD optional
  (ppstg-open :pointer))   ; IStorage** out
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $StgCreateDocfile = Win32::API::More->new('OLE32',
    'int StgCreateDocfile(LPCWSTR pwcsName, DWORD grfMode, DWORD reserved, LPVOID ppstgOpen)');
# my $ret = $StgCreateDocfile->Call($pwcsName, $grfMode, $reserved, $ppstgOpen);
# pwcsName : LPCWSTR optional -> LPCWSTR
# grfMode : STGM -> DWORD
# reserved : DWORD optional -> DWORD
# ppstgOpen : IStorage** out -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

公式の関連項目
使用する型