SccGetProjPath 函式

此函式會提示使用者輸入項目路徑，這是僅對原始檔控制外掛程式有意義的字串。 當使用者為下列專案時，就會呼叫它：

• 建立新專案

• 將現有的專案新增至版本控制

• 嘗試尋找現有的版本控制專案

語法

SCCRTN SccGetProjPath (
   LPVOID pvContext,
   HWND   hWnd,
   LPSTR  lpUser,
   LPSTR  lpProjName,
   LPSTR  lpLocalPath,
   LPSTR  lpAuxProjPath,
   BOOL   bAllowChangePath,
   LPBOOL pbNew
);

參數

pvContext

[in]原始檔控制外掛程式內容結構。

hWnd

[in]原始檔控制外掛程式可作為其提供之任何對話框之父代的 IDE 視窗句柄。

lpUser

[in， out]使用者名稱（不可超過SCC_USER_SIZE，包括 NULL 終止符）

lpProjName

[in， out]IDE 專案、專案工作區或makefile的名稱（不可超過SCC_PRJPATH_SIZE，包括 NULL 終止符）。

lpLocalPath

[in， out]專案的工作路徑。 如果 bAllowChangePath 為 TRUE，原始檔控制外掛程式可以修改此字串（不要超過_MAX_PATH，包括 null 終止符）。

lpAuxProjPath

[in， out]傳回專案路徑的緩衝區（不要超過SCC_PRJPATH_SIZE，包括 NULL 終止符）。

bAllowChangePath

[in]如果這是 TRUE，原始檔控制外掛程式可以提示並修改 lpLocalPath 字串。

pbNew

[in， out]傳入的值表示是否要建立新的專案。 傳回的值表示成功建立專案：

傳入	解釋
TRUE	使用者可以建立新的專案。
FALSE	使用者可能不會建立新的專案。

傳出	解釋
TRUE	已建立新的專案。
FALSE	已選取現有的專案。

傳回值

此函式的原始檔控制外掛程式實作應該會傳回下列其中一個值：

值	Description
SCC_OK	已成功建立或擷取專案。
SCC_I_OPERATIONCANCELED	「已取消作業」。
SCC_E_ACCESSFAILURE	存取原始檔控制系統時發生問題，可能是因為網路或爭用問題。
SCC_E_CONNECTIONFAILURE	嘗試連線到原始檔控制系統時發生問題。
SCC_E_NONSPECIFICERROR	發生未指定的錯誤。

備註

此函式的目的是讓 IDE 取得參數 lpProjName 和 lpAuxProjPath。 在原始檔控制外掛程式提示使用者提供這項信息之後，它會將這兩個字串傳回 IDE。 每當用戶開啟此專案時，IDE 會將這些字串保存在其方案檔中，並將其傳遞至 SccOpenProject 。 這些字串可讓外掛程式追蹤與專案相關聯的資訊。

第一次呼叫 函式時， lpAuxProjPath 會設定為空字串。 lProjName 也可能是空的，也可能包含 IDE 專案名稱，原始檔控制外掛程式可能會使用或忽略此名稱。 當函式成功傳回時，外掛程式會傳回兩個對應的字串。 IDE 不會假設這些字串、不會使用這些字串，也不會允許使用者修改這些字串。 如果使用者想要變更設定，IDE 會再次呼叫 SccGetProjPath ，並傳入前一次收到的相同值。 這可讓外掛程式完全控制這兩個字串。

針對 lpUser，IDE 可能會傳入用戶名稱，或者它可能只是傳入空字串的指標。 如果有使用者名稱，原始檔控制外掛程式應該使用它做為預設值。 不過，如果未傳遞任何名稱，或登入失敗且具有指定名稱，外掛程式應該會提示使用者輸入登入，並在收到有效登入時將名稱傳回 lpUser 。 因為外掛程式可能會變更此字串，因此 IDE 一律會配置大小為 （SCC_USER_LEN+1） 的緩衝區。

注意

IDE 執行的第一個動作可能是對函式或函式的SccGetProjPath呼叫SccOpenProject。 因此，這兩者都有相同的 lpUser 參數，可讓原始檔控制外掛程式在任一時間登入使用者。 即使函式的傳回指出失敗，外掛程式也必須以有效的登入名稱填入此字串。

lpLocalPath 是使用者保留項目的目錄。 它可能是空字串。 如果目前未定義任何目錄（就嘗試從原始檔控制系統下載項目的使用者而言），如果 bAllowChangePath 為 TRUE，則原始檔控制外掛程式可以提示使用者輸入，或使用其他方法將自己的字串 lpLocalPath放入 。 如果 bAllowChangePath 為 FALSE，則外掛程式不應該變更字串，因為用戶已經在指定的目錄中工作。

如果使用者建立要置於原始檔控制之下的新專案，則呼叫原始檔控制外掛程式時，可能不會實際在原始檔控制系統 SccGetProjPath 中建立該專案。 相反地，它會將字串連同 的非零值 pbNew一起傳回 ，指出專案將在原始檔控制系統中建立。

例如，如果 Visual Studio 的 [ 新增專案 ] 精靈中的使用者將他或她的專案新增至原始檔控制，Visual Studio 會呼叫此函式，而外掛程式會判斷是否能夠建立原始檔控制系統中的新專案，以包含 Visual Studio 專案。 如果使用者在完成精靈之前按兩下 [取消 ]，則永遠不會建立專案。 如果使用者按兩下 [確定]，Visual Studio 會呼叫 SccOpenProject、傳入 SCC_OPT_CREATEIFNEW，且此時會建立原始檔控制的專案。

另請參閱

• 原始檔控制外掛程式 API 函式
• SccOpenProject