Função SccGetProjPath
Essa função solicita ao usuário um caminho de projeto, que é uma cadeia de caracteres que é significativa apenas para o plug-in de controle do código-fonte. Ele é chamado quando o usuário é:
Crie um novo projeto
Adicionando um projeto existente ao controle de versão
Tentando localizar um projeto de controle de versão existente
Sintaxe
SCCRTN SccGetProjPath (
LPVOID pvContext,
HWND hWnd,
LPSTR lpUser,
LPSTR lpProjName,
LPSTR lpLocalPath,
LPSTR lpAuxProjPath,
BOOL bAllowChangePath,
LPBOOL pbNew
);
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.
lpUsuário
[dentro, fora] O nome de usuário (não deve exceder SCC_USER_SIZE, incluindo o terminador NULL)
lpProjName
[dentro, fora] O nome do projeto IDE, espaço de trabalho do projeto ou makefile (não deve exceder SCC_PRJPATH_SIZE, incluindo o terminador NULL).
lpLocalPath
[dentro, fora] A trajetória de trabalho do projeto. Se bAllowChangePath
for TRUE
, o plug-in de controle do código-fonte poderá modificar essa cadeia de caracteres (para não exceder _MAX_PATH, incluindo o terminador nulo).
lpAuxProjPath
[dentro, fora] Um buffer para o caminho do projeto retornado (para não exceder SCC_PRJPATH_SIZE, incluindo o terminador NULL).
bAllowChangePath
[em] Se isso for TRUE
, o plug-in de controle do código-fonte pode solicitar e modificar a lpLocalPath
cadeia de caracteres.
pbNovo
[dentro, fora] O valor que chega indica se um novo projeto deve ser criado. O valor retornado indica o sucesso da criação de um projeto:
Entrada | Interpretação |
---|---|
TRUE | O usuário pode criar um novo projeto. |
FALSE | O usuário não pode criar um novo projeto. |
Saída | Interpretação |
---|---|
TRUE | Um novo projeto foi criado. |
FALSE | Um projeto existente foi selecionado. |
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 | O projeto foi criado ou recuperado com êxito. |
SCC_I_OPERATIONCANCELED | a operação foi cancelada. |
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. |
SCC_E_CONNECTIONFAILURE | Houve um problema ao tentar se conectar ao sistema de controle do código-fonte. |
SCC_E_NONSPECIFICERROR | Ocorreu um erro não especificado. |
Comentários
O objetivo desta função é que o IDE adquira os parâmetros lpProjName
e lpAuxProjPath
. Depois que o plug-in de controle do código-fonte solicita ao usuário essas informações, ele passa essas duas cadeias de caracteres de volta para o IDE. O IDE persiste essas cadeias de caracteres em seu arquivo de solução e as passa para o SccOpenProject sempre que o usuário abre este projeto. Essas cadeias de caracteres permitem que o plug-in rastreie informações associadas a um projeto.
Quando a função é chamada pela primeira vez, lpAuxProjPath
é definida como uma cadeia de caracteres vazia. lProjName
também pode estar vazio ou pode conter o nome do projeto IDE, que o plug-in de controle do código-fonte pode usar ou ignorar. Quando a função retorna com êxito, o plug-in retorna as duas cadeias de caracteres correspondentes. O IDE não faz suposições sobre essas cadeias de caracteres, não as usará e não permitirá que o usuário as modifique. Se o usuário quiser alterar as configurações, o IDE chamará SccGetProjPath
novamente, passando os mesmos valores que havia recebido da vez anterior. Isso dá ao plug-in controle completo sobre essas duas cadeias de caracteres.
Para lpUser
, o IDE pode passar um nome de usuário ou pode simplesmente passar um ponteiro para uma cadeia de caracteres vazia. Se houver um nome de usuário, o plug-in de controle do código-fonte deverá usá-lo como padrão. No entanto, se nenhum nome foi passado ou se o login falhou com o nome fornecido, o plug-in deve solicitar ao usuário um login e passar o nome de volta lpUser
quando ele receber um login válido. Como o plug-in pode alterar essa cadeia de caracteres, o IDE sempre alocará um buffer de tamanho (SCC_USER_LEN
+1).
Observação
A primeira ação que o IDE executa pode ser uma chamada para a função ou a SccOpenProject
SccGetProjPath
função. Assim, ambos têm um parâmetro idêntico lpUser
, o que permite que o plug-in de controle do código-fonte faça login do usuário a qualquer momento. Mesmo que o retorno da função indique uma falha, o plug-in deve preencher essa cadeia de caracteres com um nome de login válido.
lpLocalPath
é o diretório onde o usuário mantém o projeto. Pode ser uma cadeia de caracteres vazia. Se não houver nenhum diretório definido atualmente (como no caso de um usuário tentando baixar um projeto do sistema de controle do código-fonte) e se bAllowChangePath
for TRUE
, o plug-in de controle do código-fonte pode solicitar a entrada do usuário ou usar algum outro método para colocar sua própria cadeia de caracteres no lpLocalPath
. Se bAllowChangePath
for FALSE
, o plug-in não deve alterar a cadeia de caracteres, porque o usuário já está trabalhando no diretório especificado.
Se o usuário criar um novo projeto para ser colocado sob controle do código-fonte, o plug-in de controle do código-fonte pode não criá-lo no sistema de controle do código-fonte no momento em que SccGetProjPath
for chamado. Em vez disso, ele passa de volta a cadeia de caracteres junto com um valor diferente de zero para pbNew
, indicando que o projeto será criado no sistema de controle do código-fonte.
Por exemplo, se um usuário no assistente para Novo projeto no Visual Studio adiciona seu projeto ao controle do código-fonte, o Visual Studio chama essa função e o plug-in determina se não há problema em criar um novo projeto no sistema de controle do código-fonte para conter o projeto do Visual Studio. Se o usuário clicar em Cancelar antes de concluir o assistente, o projeto nunca será criado. Se o usuário clicar em OK, o Visual Studio chamará SccOpenProject
, passando SCC_OPT_CREATEIFNEW
e o projeto controlado pelo código-fonte será criado naquele momento.