For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.
This function prompts the user for advanced options for a given command.
SCCRTN SccGetCommandOptions( LPVOID pvContext, HWND hWnd, enum SCCCOMMAND iCommand, LPCMDOPTS* ppvOptions );
[in] The source control plug-in context structure.
[in] A handle to the IDE window that the source control plug-in can use as a parent for any dialog boxes that it provides.
[in] The command for which advanced options are requested (see Command Code for possible values).
[in] The option structure (can also be
The source control plug-in implementation of this function is expected to return one of the following values:
|SCC_I_ADV_SUPPORT||The source control plug-in supports advanced options for the command.|
|SCC_I_OPERATIONCANCELED||The user cancelled the source control plug-in's Options dialog box.|
|SCC_E_OPTNOTSUPPORTED||The source control plug-in does not support this operation.|
|SCC_E_ISCHECKEDOUT||Cannot perform this operation on a file that is currently checked out.|
|SCC_E_ACCESSFAILURE||There was a problem accessing the source control system, probably due to network or contention issues. A retry is recommended.|
The IDE calls this function for the first time with
NULL to determine if the source control plug-in supports the advanced options feature for the specified command. If the plug-in does support the feature for that command, the IDE calls this function again when the user requests advanced options (usually implemented as an Advanced button in a dialog box) and supplies a non-NULL pointer for
ppvOptions that points to a
NULL pointer. The plug-in stores any advanced options specified by the user in a private structure and returns a pointer to that structure in
ppvOptions. This structure is then passed to all other Source Control Plug-in API functions that need to know about it, including subsequent calls to the
An example may help clarify this situation.
A user chooses the Get command and the IDE displays a Get dialog box. The IDE calls the
SccGetCommandOptions function with
iCommand set to
ppvOptions set to
NULL. This is interpreted by the source control plug-in as the question, "Do you have any advanced options for this command?" If the plug-in returns
SCC_I_ADV_SUPPORT, the IDE displays an Advanced button in its Get dialog box.
The first time the user clicks the Advanced button, the IDE again calls the
SccGetCommandOptions function, this time with a non-
NULL``ppvOptions that points to a
NULL pointer. The plug-in displays its own Get Options dialog box, prompts the user for information, puts that information into its own structure, and returns a pointer to that structure in
If the user clicks Advanced again in the same dialog box, the IDE calls the
SccGetCommandOptions function again without changing
ppvOptions, so that the structure is passed back to the plug-in. This enables the plug-in to reinitialize its dialog box to the values that the user had previously set. The plug-in modifies the structure in place before returning.
Finally, when the user clicks OK in the IDE's Get dialog box, the IDE calls the SccGet, passing the structure returned in
ppvOptions that contains the advanced options.