IBackgroundCopyJob2::SetNotifyCmdLine method
Specifies a program to execute if the job enters the BG_JOB_STATE_ERROR or BG_JOB_STATE_TRANSFERRED state. DO executes the program in the context of the user who called this method.
Syntax
HRESULT SetNotifyCmdLine(
[in] LPCWSTR pProgram,
[in] LPCWSTR pParameters
);
Parameters
pProgram [in]
Null-terminated string that contains the program to execute. The pProgram parameter is limited to MAX_PATH characters, not including the null terminator. You should specify a full path to the program; the method will not use the search path to locate the program.To remove command line notification, set pProgram and pParameters to NULL. The method fails if pProgram is NULL and pParameters is non-NULL.
pParameters [in]
Null-terminated string that contains the parameters of the program in pProgram. The first parameter must be the program in pProgram (use quotes if the path uses long file names). The pParameters parameter is limited to 4,000 characters, not including the null terminator. This parameter can be NULL.
Return value
This method returns the following HRESULT values, as well as others.
| Return code | Description |
|---|---|
| S_OK | Success. |
| BG_E_INVALID_STATE | The state of the job cannot be BG_JOB_STATE_CANCELLED or BG_JOB_STATE_ACKNOWLEDGED. |
| BG_E_STRING_TOO_LONG | The pProgram or pParameters string is too long. |
Remarks
DO calls the CreateProcessAsUser function to launch the program.
Your program should return an exit code of zero. If your program does not return an exit code of zero, DO checks the state of the job. If the program did not cancel or complete the job, DO calls the program again after the minimum retry delay specified for the job expires.
To execute a script, specify WScript.exe (include the full path to WScript.exe) in pProgram. The pParameters parameter should include WScript.exe, the script name, and any arguments.
If your program requires job related information, you must pass this information as arguments. Do not include environment variables, such as %system32%, in pProgram or pParameters — they are not expanded.
You should include the full path to the program. If any of the arguments in pParameters include a path that uses long file names, such as the module name, use quotes around the path.
If the program you want to execute uses the reply or download file, the program must call the IBackgroundCopyJob::Complete method to make the files available to the client.
Call the IBackgroundCopyJob::SetNotifyFlags method to specify when to execute the program. You can request command line execution only for job error or transferred events, not job modification events. Note that DO still executes the command line even if you call the SetNotifyCmdLine method after the event occurs.
If you call both the SetNotifyCmdLine method and the IBackgroundCopyJob::SetNotifyInterface method, DO will execute the command line only if the notification interface becomes invalid or the notification method that DO calls returns a failure code. For example, if the notification method that DO calls returns a E_FAIL, DO will execute the command line. However, if the notification method returns S_OK, DO will not execute the command line. If the notification method and command line execution request both fail, DO will send the notification again after the minimum retry period expires.
Note that calling the IBackgroundCopyJob::TakeOwnership method removes command line notification from the job.
Requirements
Minimum supported client |
Windows 10, version 1709 [desktop apps only] |
Minimum supported server |
Windows Server 2016 [desktop apps only] |
Header |
Deliveryoptimization.h |
IDL |
DeliveryOptimization.idl |
Library |
Dosvc.lib |
DLL |
Dosvc.dll |
IID |
IID_IBackgroundCopyJob2 is defined as 54B50739-686F-45EB-9DFF-D6A9A0FAA9AF |
See also
IBackgroundCopyJob::SetNotifyFlags