Funzione SccOpenProject
Questa funzione apre un progetto di controllo del codice sorgente esistente o ne crea uno nuovo.
Sintassi
SCCRTN SccOpenProject (
LPVOID pvContext,
HWND hWnd,
LPSTR lpUser,
LPCSTR lpProjName,
LPCSTR lpLocalProjPath,
LPSTR lpAuxProjPath,
LPCSTR lpComment,
LPTEXTOUTPROC lpTextOutProc,
LONG dwFlags
);
Parametri
pvContext
[in] Struttura del contesto del plug-in del controllo del codice sorgente.
hWnd
[in] Handle per la finestra dell'IDE che il plug-in del controllo del codice sorgente può usare come elemento padre per qualsiasi finestra di dialogo fornita.
lpUser
[in, out] Nome dell'utente (da non superare SCC_USER_SIZE, incluso il carattere di terminazione NULL).
lpProjName
[in] Stringa che identifica il nome del progetto.
lpLocalProjPath
[in] Percorso della cartella di lavoro per il progetto.
lpAuxProjPath
[in, out]Stringa ausiliaria facoltativa che identifica il progetto (non superare SCC_AUXPATH_SIZE, incluso il carattere di terminazione NULL).
lpComment
[in] Aggiungere un commento a un nuovo progetto che viene creato.
lpTextOutProc
[in] Funzione di callback facoltativa per visualizzare l'output di testo dal plug-in del controllo del codice sorgente.
dwFlags
[in] Segnala se è necessario creare un nuovo progetto se il progetto è sconosciuto al plug-in del controllo del codice sorgente. Il valore può essere una combinazione di SCC_OP_CREATEIFNEW e SCC_OP_SILENTOPEN.
Valore restituito
L'implementazione del plug-in del controllo del codice sorgente di questa funzione dovrebbe restituire uno dei valori seguenti:
| valore | Descrizione |
|---|---|
| SCC_OK | Operazione riuscita nell'apertura del progetto. |
| SCC_E_INITIALIZEFAILED | Impossibile inizializzare il progetto. |
| SCC_E_INVALIDUSER | L'utente non è riuscito ad accedere al sistema di controllo del codice sorgente. |
| SCC_E_COULDNOTCREATEPROJECT | Il progetto non esisteva prima della chiamata; il SCC_OPT_CREATEIFNEW flag è stato impostato, ma non è stato possibile creare il progetto. |
| SCC_E_PROJSYNTAXERR | Sintassi del progetto non valida. |
| SCC_E_UNKNOWNPROJECT | Il progetto è sconosciuto al plug-in del controllo del codice sorgente e il SCC_OPT_CREATEIFNEW flag non è stato impostato. |
| SCC_E_INVALIDFILEPATH | Percorso file non valido o inutilizzabile. |
| SCC_E_NOTAUTHORIZED | L'utente non è autorizzato a eseguire questa operazione. |
| SCC_E_ACCESSFAILURE | Si è verificato un problema durante l'accesso al sistema di controllo del codice sorgente, probabilmente a causa di problemi di rete o contesa. È consigliabile riprovare. |
| SCC_E_NONSPECFICERROR | Un errore non specifico; il sistema di controllo del codice sorgente non è stato inizializzato. |
Osservazioni:
L'IDE può passare un nome utente (lpUser) oppure può semplicemente passare un puntatore a una stringa vuota. Se è presente un nome utente, il plug-in del controllo del codice sorgente deve usarlo come predefinito. Tuttavia, se non è stato passato alcun nome o se l'account di accesso non è riuscito con il nome specificato, il plug-in deve richiedere all'utente di accedere e restituirà il nome valido in lpUser quando riceve un account di accesso. valido Poiché il plug-in può modificare la stringa del nome utente, l'IDE allocherà sempre un buffer di dimensioni (SCC_USER_LEN+1 o SCC_USER_SIZE, che include lo spazio per il carattere di terminazione Null.
Nota
La prima azione che l'IDE può essere necessaria per eseguire può essere una chiamata alla SccOpenProject funzione o a SccGetProjPath. Per questo motivo, entrambi hanno un parametro identico lpUser .
lpAuxProjPath e lpProjName vengono letti dal file della soluzione oppure vengono restituiti da una chiamata alla SccGetProjPath funzione. Questi parametri contengono le stringhe associate al plug-in del controllo del codice sorgente al progetto e sono significative solo per il plug-in. Se nel file della soluzione non sono presenti stringhe di questo tipo e all'utente non viene richiesto di esplorare (che restituirà una stringa tramite la SccGetProjPath funzione), l'IDE passa stringhe vuote per e lpAuxProjPath lpProjNamee prevede che questi valori vengano aggiornati dal plug-in quando questa funzione viene restituita.
lpTextOutProc è un puntatore a una funzione di callback fornita dall'IDE al plug-in del controllo del codice sorgente allo scopo di visualizzare l'output dei risultati del comando. Questa funzione di callback è descritta in dettaglio in LPTEXTOUTPROC.
Nota
Se il plug-in del controllo del codice sorgente intende sfruttare questa funzionalità, deve avere impostato il SCC_CAP_TEXTOUT flag in SccInitialize. Se tale flag non è stato impostato o se l'IDE non supporta questa funzionalità, lpTextOutProc sarà NULL.
Il dwFlags parametro controlla il risultato nel caso in cui il progetto in fase di apertura non esista attualmente. È costituito da due flag di bit e SCC_OP_CREATEIFNEW SCC_OP_SILENTOPEN. Se il progetto aperto esiste già, la funzione apre semplicemente il progetto e restituisce SCC_OK. Se il progetto non esiste e se il SCC_OP_CREATEIFNEW flag è attivo, il plug-in del controllo del codice sorgente può creare il progetto nel sistema di controllo del codice sorgente, aprirlo e restituire SCC_OK. Se il progetto non esiste e se il SCC_OP_CREATEIFNEW flag è disattivato, il plug-in deve quindi verificare la presenza del SCC_OP_SILENTOPEN flag. Se tale flag non è attivo, il plug-in potrebbe richiedere all'utente un nome di progetto. Se il flag è attivato, il plug-in deve semplicemente restituire SCC_E_UNKNOWNPROJECT.
Ordine di chiamata
Nel corso normale degli eventi, SccInitialize viene chiamato prima per aprire una sessione di controllo del codice sorgente. Una sessione può essere costituita da una chiamata a SccOpenProject, seguita da altre chiamate api plug-in plug-in del controllo del codice sorgente e terminerà con una chiamata a SccCloseProject. Tali sessioni possono essere ripetute più volte prima che venga chiamato SccUninitialize.
Se il plug-in del controllo del codice sorgente imposta il SCC_CAP_REENTRANT bit in SccInitialize, la sequenza di sessione precedente può essere ripetuta più volte in parallelo. Diverse pvContext strutture tengono traccia delle diverse sessioni, in cui ognuna pvContext è associata a un progetto aperto alla volta. In base al pvContext parametro , il plug-in può determinare il progetto a cui viene fatto riferimento in una determinata chiamata. Se il bit SCC_CAP_REENTRANT di funzionalità non è impostato, i plug-in di controllo del codice sorgente non rientrano nella capacità di lavorare con più progetti.
Nota
Il SCC_CAP_REENTRANT bit è stato introdotto nella versione 1.1 dell'API plug-in del controllo del codice sorgente. Non è impostato o viene ignorato nella versione 1.0 e si presuppone che tutti i plug-in del controllo del codice sorgente della versione 1.0 siano non pertinenti.