Função SccGetCommandOptions
Essa função solicita ao usuário opções avançadas para um determinado comando.
Sintaxe
SCCRTN SccGetCommandOptions(
LPVOID pvContext,
HWND hWnd,
enum SCCCOMMAND iCommand,
LPCMDOPTS* ppvOptions
);
Parâmetros
pvContexto
[em] A estrutura de contexto do plug-in de controle do código-fonte.
hWnd
[em] Um identificador para a janela do IDE que o plug-in de controle do código-fonte pode usar como pai para quaisquer caixas de diálogo que ele forneça.
iComando
[em] O comando para o qual as opções avançadas são solicitadas (consulte Código de comando para obter valores possíveis).
ppvOpções
[em] A estrutura da opção (também pode ser NULL).
Valor retornado
Espera-se que a implementação do plug-in de controle do código-fonte dessa função retorne um dos seguintes valores:
| Valor | Descrição |
|---|---|
| SCC_OK | Êxito. |
| SCC_I_ADV_SUPPORT | O plug-in de controle do código-fonte oferece suporte a opções avançadas para o comando. |
| SCC_I_OPERATIONCANCELED | O usuário cancelou a caixa de diálogo Opções do plug-in de controle do código-fonte. |
| SCC_E_OPTNOTSUPPORTED | O plug-in de controle do código-fonte não oferece suporte a essa operação. |
| SCC_E_ISCHECKEDOUT | Não é possível executar essa operação em um arquivo que está com check-out no momento. |
| SCC_E_ACCESSFAILURE | Houve um problema ao acessar o sistema de controle do código-fonte, provavelmente devido a problemas de rede ou contenção. Recomenda-se uma nova tentativa. |
| SCC_E_NONSPECIFICERROR | Falha inespecífica. |
Comentários
O IDE chama essa função pela primeira vez para ppvOptions=NULL determinar se o plug-in de controle do código-fonte oferece suporte ao recurso de opções avançadas para o comando especificado. Se o plug-in oferecer suporte ao recurso para esse comando, o IDE chamará essa função novamente quando o usuário solicitar opções avançadas (geralmente implementadas como um botão Avançado em uma caixa de diálogo) e fornecerá um ponteiro não NULL para que aponte para ppvOptions um NULL ponteiro. O plug-in armazena todas as opções avançadas especificadas pelo usuário em uma estrutura privada e retorna um ponteiro para essa estrutura no ppvOptions. Essa estrutura é então passada para todas as outras funções da API do plug-in de controle do código-fonte que precisam saber sobre ela, incluindo chamadas subsequentes para a SccGetCommandOptions função.
Um exemplo pode ajudar a esclarecer essa situação.
Um usuário escolhe o comando Get e o IDE exibe uma caixa de diálogo Get. O IDE chama a SccGetCommandOptions função com iCommand set como SCC_COMMAND_GET e ppvOptions set como NULL. Isso é interpretado pelo plug-in de controle do código-fonte como a pergunta: "Você tem alguma opção avançada para este comando?" Se o plug-in retornar SCC_I_ADV_SUPPORT, o IDE exibirá um botão Avançado em sua caixa de diálogo Obter .
Na primeira vez que o usuário clica no botão Avançado , o IDE chama novamente a SccGetCommandOptions função, desta vez com um não-queNULL``ppvOptions aponta para um NULL ponteiro. O plug-in exibe sua própria caixa de diálogo Obter Opções, solicita informações ao usuário, coloca essas informações em sua própria estrutura e retorna um ponteiro para essa estrutura no ppvOptions.
Se o usuário clicar em Avançado novamente na mesma caixa de diálogo, o IDE chamará a função novamente sem alterar ppvOptions, para que a SccGetCommandOptions estrutura seja passada de volta para o plug-in. Isso permite que o plug-in reinicialize sua caixa de diálogo para os valores que o usuário havia definido anteriormente. O plug-in modifica a estrutura no lugar antes de retornar.
Finalmente, quando o usuário clica em OK na caixa de diálogo Obter do IDE, o IDE chama o SccGet, passando a estrutura retornada que ppvOptions contém as opções avançadas.
Observação
O comando SCC_COMMAND_OPTIONS é usado quando o IDE exibe uma caixa de diálogo Opções que permite ao usuário definir preferências que controlam como a integração funciona. Se o plug-in de controle do código-fonte quiser fornecer sua própria caixa de diálogo de preferências, ele poderá exibi-la a partir de um botão Avançado na caixa de diálogo de preferências do IDE. O plug-in é o único responsável por obter e manter essas informações; o IDE não o usa nem o modifica.