SccOpenProject, funkcja
Ta funkcja otwiera istniejący projekt kontroli źródła lub tworzy nowy.
Składnia
SCCRTN SccOpenProject (
LPVOID pvContext,
HWND hWnd,
LPSTR lpUser,
LPCSTR lpProjName,
LPCSTR lpLocalProjPath,
LPSTR lpAuxProjPath,
LPCSTR lpComment,
LPTEXTOUTPROC lpTextOutProc,
LONG dwFlags
);
Parametry
pvContext
[in] Struktura kontekstu wtyczki kontroli źródła.
hWnd
[in] Dojście do okna środowiska IDE, którego wtyczka kontroli źródła może używać jako elementu nadrzędnego dla wszystkich okien dialogowych, które udostępnia.
lpUser
[in, out] Nazwa użytkownika (nie może przekraczać SCC_USER_SIZE, w tym terminator null).
lpProjName
[in] Ciąg identyfikujący nazwę projektu.
lpLocalProjPath
[in] Ścieżka do folderu roboczego projektu.
lpAuxProjPath
[in, out]Opcjonalny ciąg pomocniczy identyfikujący projekt (nie przekraczać SCC_AUXPATH_SIZE, w tym terminator null).
lpComment
[in] Oznacz komentarz do nowego projektu, który jest tworzony.
lpTextOutProc
[in] Opcjonalna funkcja wywołania zwrotnego do wyświetlania danych wyjściowych tekstu z wtyczki kontroli źródła.
dwFlags
[in] Sygnalizuje, czy nowy projekt należy utworzyć, jeśli projekt jest nieznany wtyczki kontroli źródła. Wartość może być kombinacją wartości SCC_OP_CREATEIFNEW i SCC_OP_SILENTOPEN.
Wartość zwracana
Implementacja wtyczki kontroli źródła tej funkcji powinna zwrócić jedną z następujących wartości:
| Wartość | Opis |
|---|---|
| SCC_OK | Powodzenie podczas otwierania projektu. |
| SCC_E_INITIALIZEFAILED | Nie można zainicjować projektu. |
| SCC_E_INVALIDUSER | Użytkownik nie mógł zalogować się do systemu kontroli źródła. |
| SCC_E_COULDNOTCREATEPROJECT | Projekt nie istniał przed wywołaniem; flaga SCC_OPT_CREATEIFNEW została ustawiona, ale nie można utworzyć projektu. |
| SCC_E_PROJSYNTAXERR | Nieprawidłowa składnia projektu. |
| SCC_E_UNKNOWNPROJECT | Projekt jest nieznany wtyczki kontroli źródła, a flaga nie została ustawiona SCC_OPT_CREATEIFNEW . |
| SCC_E_INVALIDFILEPATH | Nieprawidłowa lub bezużyteczna ścieżka pliku. |
| SCC_E_NOTAUTHORIZED | Użytkownik nie może wykonać tej operacji. |
| SCC_E_ACCESSFAILURE | Wystąpił problem podczas uzyskiwania dostępu do systemu kontroli źródła, prawdopodobnie z powodu problemów z siecią lub rywalizacją. Zalecane jest ponowienie próby. |
| SCC_E_NONSPECFICERROR | Nieokreślona awaria; system kontroli źródła nie został zainicjowany. |
Uwagi
Środowisko IDE może przekazać nazwę użytkownika (lpUser) lub po prostu przekazać wskaźnik do pustego ciągu. Jeśli istnieje nazwa użytkownika, wtyczka kontroli źródła powinna używać jej jako domyślnej. Jeśli jednak nie przekazano żadnej nazwy lub jeśli logowanie nie powiodło się z daną nazwą, wtyczka powinna monitować użytkownika o zalogowanie się i zwróci prawidłową nazwę, lpUser gdy otrzyma prawidłową nazwę logowania. , ponieważ wtyczka może zmienić ciąg nazwy użytkownika, środowisko IDE zawsze przydzieli bufor o rozmiarze (SCC_USER_LEN+1 lub SCC_USER_SIZE, który zawiera miejsce dla terminatora o wartości null).
Uwaga
Pierwszą akcją, która może być wymagana do wykonania w środowisku IDE, może być wywołanie SccOpenProject funkcji lub SccGetProjPath. Z tego powodu oba mają identyczny lpUser parametr.
lpAuxProjPath i lpProjName są odczytywane z pliku rozwiązania lub są zwracane z wywołania funkcji SccGetProjPath . Te parametry zawierają ciągi, które wtyczka kontroli źródła kojarzy z projektem i mają znaczenie tylko dla wtyczki. Jeśli nie ma takich ciągów w pliku rozwiązania, a użytkownik nie został poproszony o przeglądanie (co zwróci ciąg za pośrednictwem SccGetProjPath funkcji), środowisko IDE przekazuje puste ciągi zarówno dla parametrów , jak lpAuxProjPath i lpProjNamei i oczekuje, że te wartości zostaną zaktualizowane przez wtyczkę, gdy ta funkcja zwróci.
lpTextOutProc jest wskaźnikiem do funkcji wywołania zwrotnego dostarczonej przez środowisko IDE do wtyczki kontroli źródła na potrzeby wyświetlania danych wyjściowych wyniku polecenia. Ta funkcja wywołania zwrotnego została szczegółowo opisana w temacie LPTEXTOUTPROC.
Uwaga
Jeśli wtyczka kontroli źródła zamierza skorzystać z tej funkcji, musi ona ustawić flagę SCC_CAP_TEXTOUT w SccInitialize. Jeśli ta flaga nie została ustawiona lub jeśli środowisko IDE nie obsługuje tej funkcji, lpTextOutProc będzie to NULL.
Parametr dwFlags kontroluje wynik w przypadku, gdy otwarty projekt nie istnieje obecnie. Składa się z dwóch bitów i SCC_OP_CREATEIFNEW SCC_OP_SILENTOPEN. Jeśli otwarty projekt już istnieje, funkcja po prostu otwiera projekt i zwraca wartość SCC_OK. Jeśli projekt nie istnieje i jeśli flaga SCC_OP_CREATEIFNEW jest włączona, wtyczka kontroli źródła może utworzyć projekt w systemie kontroli źródła, otworzyć go i zwrócić .SCC_OK Jeśli projekt nie istnieje i jeśli flaga SCC_OP_CREATEIFNEW jest wyłączona, wtyczka powinna sprawdzić flagę SCC_OP_SILENTOPEN . Jeśli ta flaga nie jest włączona, wtyczka może wyświetlić monit o podanie nazwy projektu. Jeśli ta flaga jest włączona, wtyczka powinna po prostu zwrócić wartość SCC_E_UNKNOWNPROJECT.
Kolejność wywoływania
W normalnym przebiegu zdarzeń funkcja SccInitialize zostanie wywołana jako pierwsza w celu otwarcia sesji kontroli źródła. Sesja może składać się z wywołania SccOpenProjectmetody , a następnie innych wywołań funkcji interfejsu API kontroli kodu źródłowego i zakończy się wywołaniem polecenia SccCloseProject. Takie sesje mogą być powtarzane kilka razy, zanim wywołana jest funkcja SccUninitialize .
Jeśli wtyczka kontroli źródła ustawia SCC_CAP_REENTRANT bit w SccInitializeelemecie , powyższy sekwencja sesji może być powtarzana wiele razy równolegle. Różne pvContext struktury śledzą różne sesje, w których każda z nich pvContext jest skojarzona z jednym otwartym projektem naraz. Na podstawie parametru pvContext wtyczka może określić, do którego projektu odwołuje się dowolny konkretny wywołanie. Jeśli bit SCC_CAP_REENTRANT możliwości nie jest ustawiony, niereententne wtyczki kontroli źródła są ograniczone do pracy z wieloma projektami.
Uwaga
Bit SCC_CAP_REENTRANT został wprowadzony w wersji 1.1 interfejsu API wtyczki kontroli źródła. Nie jest on ustawiony lub jest ignorowany w wersji 1.0, a wszystkie wtyczki kontroli źródła w wersji 1.0 są zakładane jako niezgodne.