Função SccOpenProject
Essa função abre um projeto de controle do 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
pvContext
[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 qualquer caixa de diálogo fornecida.
Usuário lp
[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 em 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 do código-fonte. |
| SCC_E_COULDNOTCREATEPROJECT | O projeto não existia antes da chamada; O sinalizador SCC_OPT_CREATEIFNEW foi definido, 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 sinalizador SCC_OPT_CREATEIFNEW 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 esta 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 efetue login e retornará o nome lpUser válido quando receber um login. válido Como o plug-in pode alterar a cadeia de caracteres de 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 obrigado a executar pode ser uma chamada para a SccOpenProject função ou o SccGetProjPath. Por esse motivo, ambos têm um parâmetro idêntico lpUser .
lpAuxProjPath e lpProjName são lidos 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 significativos apenas para o plug-in. Se nenhuma dessas cadeias de caracteres estiver no arquivo de solução e o usuário não tiver sido solicitado a procurar (o que retornaria uma cadeia de caracteres por meio da SccGetProjPath função), o IDE passará cadeias de caracteres vazias para ambos lpAuxProjPath e lpProjName, e espera 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 do código-fonte 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 tiver sido definido ou se o IDE não suportar esse recurso, lpTextOutProc será NULL.
O dwFlags parâmetro controla o resultado caso o projeto que está sendo aberto não exista no momento. Consiste em dois bitflags SCC_OP_CREATEIFNEW e SCC_OP_SILENTOPEN. Se o projeto que está sendo aberto já existir, a função simplesmente abre o projeto e retorna SCC_OK. Se o projeto não existir e se o SCC_OP_CREATEIFNEW sinalizador estiver ativado, o plug-in de controle do código-fonte poderá criar o projeto no sistema de controle do código-fonte, abri-lo e retornar SCC_OK. Se o projeto não existir e se o SCC_OP_CREATEIFNEW sinalizador estiver desativado, o plug-in deverá verificar o SCC_OP_SILENTOPEN sinalizador. 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 SccOpenProject, seguida por outras chamadas de função de API do Plug-in de Controle do Código-Fonte e terminará com uma chamada para o SccCloseProject. Essas 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 em SccInitialize, a sequência de sessão acima poderá ser repetida várias vezes em paralelo. Diferentes pvContext estruturas rastreiam as diferentes sessões, nas quais cada pvContext uma está associada a um projeto aberto por vez. Com base no pvContext 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 do código-fonte 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 do plug-in de controle do código-fonte. Ele não é definido ou é ignorado na versão 1.0, e todos os plug-ins de controle do código-fonte da versão 1.0 são considerados não reentrantes.