IMAPIFolder::CopyFolder
適用対象: Outlook 2013 | Outlook 2016
サブフォルダーをコピーまたは移動します。
HRESULT CopyFolder(
ULONG cbEntryID,
LPENTRYID lpEntryID,
LPCIID lpInterface,
LPVOID lpDestFolder,
LPSTR lpszNewFolderName,
ULONG_PTR ulUIParam,
LPMAPIPROGRESS lpProgress,
ULONG ulFlags
);
パラメーター
cbEntryID
[in] lpEntryID パラメーターによって指されるエントリ識別子のバイト数。
lpEntryID
[in]コピーまたは移動するサブフォルダーのエントリ識別子へのポインター。
lpInterface
[in] lpDestFolder パラメーターが指すフォルダーへのアクセスに使用するインターフェイスを表すインターフェイス識別子 (IID) へのポインター。 NULL を渡すと、サービス プロバイダーは標準フォルダー インターフェイス IMAPIFolder : IMAPIContainer を返します。 lpInterface の有効な値には、IID_IUnknown、IID_IMAPIProp、IID_IMAPIContainer、IID_IMAPIFolderが含まれます。
lpDestFolder
[in]コピーまたは移動されたサブフォルダーを受け取る開いているフォルダーへのポインター。
lpszNewFolderName
[in]コピーまたは移動したフォルダーの新しいコピー先の名前へのポインター。 lpszNewFolderName が NULL に設定されている場合は、コピー先フォルダーの名前にソース サブフォルダーの名前が使用されます。
ulUIParam
[in]進行状況インジケーターの親ウィンドウへのハンドル。 ulFLags パラメーターのFOLDER_DIALOG フラグが設定されていない限り、ulUIParam パラメーターは無視されます。
lpProgress
[in]進行状況インジケーターを表示する進行状況オブジェクトへのポインター。 LPProgress で NULL が渡された場合、メッセージ ストア プロバイダーは MAPI 進行状況オブジェクトの実装を使用して進行状況インジケーターを表示します。 lpProgress パラメーターは、ulFlags でFOLDER_DIALOG フラグが設定されていない限り無視されます。
ulFlags
[in]コピーまたは移動操作を制御するフラグのビットマスク。 次のフラグを設定できます。
COPY_SUBFOLDERS
コピーするサブフォルダー内のすべてのサブフォルダーもコピーする必要があります。 コピー操作にCOPY_SUBFOLDERSが設定されていない場合は、 lpEntryID によって識別されるサブフォルダーのみがコピーされます。 移動操作では、フラグが設定されているかどうかに関係なく、COPY_SUBFOLDERS動作が既定値になります。
FOLDER_DIALOG
進行状況インジケーターの表示を要求します。
FOLDER_MOVE
サブフォルダーは、コピーされるのではなく移動されます。 FOLDER_MOVEが設定されていない場合、サブフォルダーがコピーされます。
MAPI_DECLINE_OK
サポート オブジェクトの IMAPISupport::D oCopyTo または IMAPISupport::D oCopyProps メソッドを呼び出して CopyFolder を実装する場合、CopyFolder は代わりにすぐにMAPI_E_DECLINE_COPYを返す必要があることをメッセージ ストア プロバイダーに通知します。
MAPI_UNICODE
コピー先フォルダーの名前は Unicode 形式です。 MAPI_UNICODE フラグが設定されていない場合、フォルダー名は ANSI 形式です。
戻り値
S_OK
指定したフォルダーが正常にコピーまたは移動されました。
MAPI_E_BAD_CHARWIDTH
MAPI_UNICODE フラグが設定され、メッセージ ストア プロバイダーが Unicode をサポートしていないか、MAPI_UNICODEが設定されておらず、メッセージ ストア プロバイダーが Unicode のみをサポートしています。
MAPI_E_COLLISION
移動またはコピーするフォルダーの名前は、移動先フォルダー内のサブフォルダーの名前と同じです。 メッセージ ストア プロバイダーには、一意のフォルダー名が必要です。
MAPI_E_DECLINE_COPY
プロバイダーはサポート オブジェクト メソッドを呼び出してこのメソッドを実装し、呼び出し元は MAPI_DECLINE_OK フラグを渡しました。
MAPI_E_FOLDER_CYCLE
ソース フォルダーには、直接または間接的にコピー先フォルダーが含まれています。 この条件が検出される前に重要な作業が実行された可能性があるため、ソースフォルダーとコピー先フォルダーが部分的に変更される可能性があります。
MAPI_W_PARTIAL_COMPLETION
呼び出しは成功しましたが、すべてのエントリが正常にコピーされたわけではありません。 この警告が返されたら、呼び出しは成功として処理する必要があります。 この警告をテストするには、 HR_FAILED マクロを使用します。 詳細については、「 エラー処理にマクロを使用する」を参照してください。
注釈
IMAPIFolder::CopyFolder メソッドは、ある場所から別の場所にサブフォルダーをコピーまたは移動します。 コピーまたは移動されるサブフォルダーは、コピー先フォルダーにサブフォルダーとして追加されます。
実装に関するメモ
COPY_SUBFOLDERS フラグを設定して示すように、コピー操作または移動操作に複数のフォルダーが含まれる場合は、各フォルダーに対して可能な限り完全に操作を実行します。 移動またはコピーするフォルダーの 1 つが存在しないか、既に移動または他の場所にコピーされている場合があります。 メモリ不足、ディスク領域の不足、メッセージ ストアの破損など、制御できないエラーが発生しない限り、操作を途中で停止しないでください。
コピーしたメッセージ内のすべてのメッセージ エントリ識別子を保持してみてください。 また、エントリ識別子を保持する必要がありますが、必須ではありません。
呼び出し側への注意
これらの戻り値は、次の条件で想定します。
| Condition | 戻り値 |
|---|---|
| CopyFolder は、すべてのメッセージとサブフォルダーを正常にコピーまたは移動しました。 | S_OK |
| CopyFolder は、すべてのメッセージとサブフォルダーを正常にコピーまたは移動できませんでした。 | MAPI_W_PARTIAL_COMPLETIONまたはMAPI_E_NOT_FOUND |
| CopyFolder を完了できませんでした。 | MAPI_E_NOT_FOUNDを除くすべてのエラー値 |
CopyFolder が完了できない場合は、作業が行われなかったと想定しないでください。 CopyFolder は、エラーが発生する前に、1 つ以上のメッセージとサブフォルダーをコピーまたは移動できた可能性があります。
存在しないフォルダーのエントリ識別子が lpEntryID に渡された場合、 CopyFolder はメッセージ ストアの実装に応じて、MAPI_W_PARTIAL_COMPLETIONまたはMAPI_E_NOT_FOUNDを返します。
メッセージ ストア プロバイダーによっては、元のメッセージのエントリ識別子がコピーされたメッセージに保持される場合と保持されない場合があります。 エントリ識別子は可能な限り保持する必要がありますが、必須ではありません。 一般に、次のシナリオに依存できます。
2 種類のメッセージ ストア間でフォルダーを移動すると、エントリ識別子が変更されていることが保証されます。
同じ種類の 2 つのメッセージ ストア間でフォルダーを移動すると、ほとんどの場合、エントリ識別子が変更されます。
同じメッセージ ストア内の別の場所にフォルダーを移動すると、メッセージ ストア プロバイダーによっては、エントリ識別子が変更される場合と変更されない場合があります。
MFCMAPI リファレンス
MFCMAPI のサンプル コードについては、次の表を参照してください。
| ファイル | 関数 | コメント |
|---|---|---|
| MsgStoreDlg.cpp |
CMsgStoreDlg::OnPasteFolder |
MFCMAPI では、 IMAPIFolder::CopyFolder メソッドを使用して、フォルダーをある場所から別の場所にコピーします。 MFCMAPI は、コピー操作中にソース フォルダーを記憶し、貼り付け操作中にコピーを実際に実行します。 |