Importing and Exporting with Directory Access Functions

The most basic directory operations can be performed by calling the BatchImport or BatchExport functions, specifying a minimum amount of information, and using default settings.

Note  The most important task when using directory access functions is to set the parameters used in function calls, such as the BEXPORT_PARMS structure used with the BatchExport function. For more information, see Structures.

    To invoke a basic export operation

1. Export selected objects into a file using the BatchExport function. Designate the export file by setting the pszExportFile member of the BEXPORT_PARMS structure, which is the only parameter to BatchExport. In this file, you can use a header line that indicates which attributes to export and that will be read by the export function call. This function then exports its data to the export file by overwriting its contents, if any. The header line is preserved. In other words, the BatchExport function both reads from and writes to the export file.
2. Designate the location in the directory information tree (DIT) from which objects are to be exported by specifying the basepoint container (with the pszBasePoint member and the pszContainer member) and the server (with pszServerName). See Controlling Export with BasePoint, Container, and Export Flags.

You can perform more complex export operations and tailor them to your specific needs, whether you are exporting every recipient in the DIT or a single object. You extend the capabilities of the directory access functions by setting values for control flags — an array of flags that comprise the dwFlags member. You can also assign values to other fields in the BEXPORT_PARMS structure. Some of these options are listed here:

• Export data back to your application instead of a file by using export callbacks. To do this, specify the callback function in the pfnExportEntry member of the ExportCallback structure (of type EXPORT_CALLBACK), which is passed to BatchExport in BEXPORT_PARMS. This mechanism overrides the default behavior, which is to write the exported data to a file. For more information on callback functions, see Using Directory Access Callback Functions.
• Specify attributes to be exported programmatically in the pAttributes member instead of reading them from a file.
• Perform error handling with the error callback mechanism and the ErrorCallback member.
• Enable progress display with the progress callback mechanism and the ProgressCallBacks member.
• Restrict the export to classes of objects that you specify in the rgpszClasses member.
• Restrict the export to changed objects, specified with ulUSNBase. This restriction uses update sequence numbers (USNs), which are explained in Exporting and Importing Changed Objects.
• Export a single object by defining an empty string for the pszParentContainer member and setting the DAPI_EXPORT_BASEPOINT_ONLY flag. Refer to the pszParentContainer and pszBasePoint members, and the DAPI_EXPORT_BASEPOINT_ONLY flag.

In some cases, you need to combine the use of a parameter with a specific flag. For example, pass in a value for ulUSNBase to restrict an export to objects that have changed.

You can also fine-tune import operations. Here are several examples:

• Import a single object using the DAPIWrite function. This operation allows you to create, modify, or delete an object in the DIT.
• Use an existing mailbox to provide default attributes when importing new mailboxes. Do this by setting the pszCreateTemplate member to the distinguished name (DN) of the template mailbox. Refer to the pszCreateTemplate parameter, and see Using Template Objects.
• Configure the directory import system to automatically create a new Windows NT Server account when it imports a new recipient. Do this by setting the DAPI_CREATE_NT_ACCOUNT flag when calling either the BatchImport or the DAPIStart function. See Creating an Associated Windows NT Account. You can also associate this new recipient with an existing Windows NT Server account.

Note  Characters used in a distinguished name (DN) or in any string used to build a DN (such as pszBasePoint and pszContainer) must be in the 0x0020 to 0x007E range. Any characters outside this range are first mapped to ANSI. DNs are further mapped to 7-bit ASCII characters. When a function such as DAPIWrite has to map characters, it returns a warning.