Função SccOpenProject
Essa função abre um projeto de controle de código-fonte existente ou cria um novo.
Sintaxe
SCCRTN SccOpenProject (
LPVOID pvContext,
HWND hWnd,
LPSTR lpUser,
LPCSTR lpProjName,
LPCSTR lpLocalProjPath,
LPSTR lpAuxProjPath,
LPCSTR lpComment,
LPTEXTOUTPROC lpTextOutProc,
LONG dwFlags
);
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 do usuário (não deve exceder SCC_USER_SIZE, incluindo o terminador NULL).
lpProjName
[em] A cadeia de caracteres que identifica o nome do projeto.
lpLocalProjPath
[em] O caminho para a pasta de trabalho do projeto.
lpAuxProjPath
[dentro, fora] Uma cadeia de caracteres auxiliar opcional que identifica o projeto (não deve exceder SCC_AUXPATH_SIZE, incluindo o terminador NULL).
lpComentário
[em] Comente para um novo projeto que está sendo criado.
lpTextOutProc
[em] Uma função de retorno de chamada opcional para exibir a saída de texto do plug-in de controle do código-fonte.
dwFlags
[em] Sinaliza se um novo projeto precisa ser criado se o projeto for desconhecido para o plug-in de controle do código-fonte. O valor pode ser uma combinação de SCC_OP_CREATEIFNEW e SCC_OP_SILENTOPEN.
Valor de retorno
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 | Sucesso na abertura do projeto. |
| SCC_E_INITIALIZEFAILED | O projeto não pôde ser inicializado. |
| SCC_E_INVALIDUSER | O usuário não pôde efetuar login no sistema de controle de origem. |
| SCC_E_COULDNOTCREATEPROJECT | O projeto não existia antes da chamada; A SCC_OPT_CREATEIFNEW bandeira foi definida, mas o projeto não pôde ser criado. |
| SCC_E_PROJSYNTAXERR | Sintaxe de projeto inválida. |
| SCC_E_UNKNOWNPROJECT | O projeto é desconhecido para o plug-in de controle do código-fonte e o SCC_OPT_CREATEIFNEW sinalizador não foi definido. |
| SCC_E_INVALIDFILEPATH | Caminho de arquivo inválido ou inutilizável. |
| SCC_E_NOTAUTHORIZED | O usuário não tem permissão para executar essa operação. |
| 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_NONSPECFICERROR | Uma falha inespecífica; O sistema de controle do código-fonte não foi inicializado. |
Comentários
O IDE pode passar um nome de usuário (lpUser), 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 que o usuário faça login e retornará o nome válido quando lpUser receber um login. válido Como o plug-in pode alterar a cadeia de caracteres do nome de usuário, o IDE sempre alocará um buffer de tamanho (SCC_USER_LEN+1 ou SCC_USER_SIZE, que inclui espaço para o terminador nulo).
Observação
A primeira ação que o IDE pode ser necessário executar pode ser uma chamada para a SccOpenProject função ou o SccGetProjPath. Por esse motivo, ambos possuem um parâmetro idêntico lpUser .
lpAuxProjPath elpProjName são lidos a partir do arquivo de solução ou são retornados de uma chamada para a SccGetProjPath função. Esses parâmetros contêm as cadeias de caracteres que o plug-in de controle do código-fonte associa ao projeto e são significativas apenas para o plug-in. Se essas cadeias de caracteres não estiverem no arquivo de solução e o usuário não tiver sido solicitado a navegar (o que retornaria uma cadeia de caracteres por meio da função), o SccGetProjPath IDE passará cadeias de caracteres vazias para ambos lpAuxProjPath e , e lpProjNameespera que esses valores sejam atualizados pelo plug-in quando essa função retornar.
lpTextOutProc é um ponteiro para uma função de retorno de chamada fornecida pelo IDE para o plug-in de controle de origem com a finalidade de exibir a saída do resultado do comando. Essa função de retorno de chamada é descrita em detalhes em LPTEXTOUTPROC.
Observação
Se o plug-in de controle do código-fonte pretende tirar proveito disso, ele deve ter definido o SCC_CAP_TEXTOUT sinalizador no SccInitialize. Se esse sinalizador não foi definido, ou se o IDE não oferece suporte a esse recurso, lpTextOutProc será NULL.
O dwFlags parâmetro controla o resultado caso o projeto que está sendo aberto não exista no momento. Ele consiste em dois bitflags, SCC_OP_CREATEIFNEW e SCC_OP_SILENTOPEN. Se o projeto que está sendo aberto já existe, a função simplesmente abre o projeto e retorna SCC_OK. Se o projeto não existir e se o sinalizador estiver ativado, o plug-in de controle do código-fonte poderá criar o SCC_OP_CREATEIFNEW projeto no sistema de controle do código-fonte, abri-lo e retornar SCC_OK. Se o projeto não existir e se o sinalizador estiver desativado, o SCC_OP_CREATEIFNEW plug-in deverá verificar se há sinalizador SCC_OP_SILENTOPEN . Se esse sinalizador não estiver ativado, o plug-in poderá solicitar ao usuário um nome de projeto. Se esse sinalizador estiver ativado, o plug-in deve simplesmente retornar SCC_E_UNKNOWNPROJECT.
Ordem de chamada
No curso normal dos eventos, o SccInitialize seria chamado primeiro para abrir uma sessão de controle do código-fonte. Uma sessão pode consistir em uma chamada para , seguida por outras chamadas de função de API de plug-in de controle de código-fonte e será encerrada com uma chamada para SccOpenProjecto SccCloseProject. Tais sessões podem ser repetidas várias vezes antes que o SccUninitialize seja chamado.
Se o plug-in de controle do código-fonte definir o SCC_CAP_REENTRANT bit no SccInitialize, a sequência de sessão acima poderá ser repetida várias vezes em paralelo. Diferentes pvContext estruturas acompanham as diferentes sessões, nas quais cada uma está associada a um projeto aberto de cada pvContext vez. Com base nopvContext parâmetro, o plug-in pode determinar qual projeto é referenciado em qualquer chamada específica. Se o bit SCC_CAP_REENTRANT de capacidade não estiver definido, os plug-ins de controle de origem não reentrantes serão limitados em sua capacidade de trabalhar com vários projetos.
Observação
O SCC_CAP_REENTRANT bit foi introduzido na versão 1.1 da API de plug-in de controle de código-fonte. Ele não está definido ou é ignorado na versão 1.0, e todos os plug-ins de controle de origem da versão 1.0 são assumidos como não reentrantes.