Fonction SccOpenProject
Cette fonction ouvre un projet de contrôle de code source existant ou en crée un.
Syntaxe
SCCRTN SccOpenProject (
LPVOID pvContext,
HWND hWnd,
LPSTR lpUser,
LPCSTR lpProjName,
LPCSTR lpLocalProjPath,
LPSTR lpAuxProjPath,
LPCSTR lpComment,
LPTEXTOUTPROC lpTextOutProc,
LONG dwFlags
);
Paramètres
pvContext
[in] Structure de contexte du plug-in de contrôle de code source.
hWnd
[in] Handle vers la fenêtre IDE que le plug-in de contrôle de code source peut utiliser comme parent pour toutes les boîtes de dialogue qu’il fournit.
lpUser
[in, out] Nom de l’utilisateur (à ne pas dépasser SCC_USER_SIZE, y compris le terminateur NULL).
lpProjName
[in] Chaîne identifiant le nom du projet.
lpLocalProjPath
[in] Chemin d’accès au dossier de travail du projet.
lpAuxProjPath
[in, out]Chaîne auxiliaire facultative identifiant le projet (sans dépasser SCC_AUXPATH_SIZE, y compris la marque de fin NULL).
lpComment
[in] Commentez un projet en cours de création.
lpTextOutProc
[in] Fonction de rappel facultative pour afficher la sortie du texte à partir du plug-in de contrôle de code source.
dwFlags
[in] Indique si un nouveau projet doit être créé si le projet est inconnu du plug-in de contrôle de code source. La valeur peut être une combinaison de SCC_OP_CREATEIFNEW et SCC_OP_SILENTOPEN.
Valeur de retour
L’implémentation du plug-in de contrôle de code source de cette fonction est censée retourner l’une des valeurs suivantes :
| Valeur | Description |
|---|---|
| SCC_OK | Réussite de l’ouverture du projet. |
| SCC_E_INITIALIZEFAILED | Impossible d’initialiser le projet. |
| SCC_E_INVALIDUSER | L’utilisateur n’a pas pu se connecter au système de contrôle de code source. |
| SCC_E_COULDNOTCREATEPROJECT | Le projet n’existait pas avant l’appel ; l’indicateur SCC_OPT_CREATEIFNEW a été défini, mais le projet n’a pas pu être créé. |
| SCC_E_PROJSYNTAXERR | Syntaxe de projet non valide. |
| SCC_E_UNKNOWNPROJECT | Le projet est inconnu du plug-in de contrôle de code source et l’indicateur SCC_OPT_CREATEIFNEW n’a pas été défini. |
| SCC_E_INVALIDFILEPATH | Chemin d’accès de fichier non valide ou inutilisable. |
| SCC_E_NOTAUTHORIZED | L’utilisateur n’est pas autorisé à effectuer cette opération. |
| SCC_E_ACCESSFAILURE | Il y a eu un problème d’accès au système de contrôle de code source, probablement en raison de problèmes de réseau ou de contention. Une nouvelle tentative est recommandée. |
| SCC_E_NONSPECFICERROR | Un échec non spécifique ; le système de contrôle de code source n’a pas été initialisé. |
Notes
L’IDE peut passer un nom d’utilisateur (lpUser), ou il peut simplement passer un pointeur vers une chaîne vide. S’il existe un nom d’utilisateur, le plug-in de contrôle de code source doit l’utiliser comme valeur par défaut. Toutefois, si aucun nom n’a été passé ou si la connexion a échoué avec le nom donné, le plug-in doit inviter l’utilisateur à se connecter et retournera le nom lpUser valide lorsqu’il reçoit une connexion. valide, car le plug-in peut modifier la chaîne de nom d’utilisateur, l’IDE alloue toujours une mémoire tampon de taille (SCC_USER_LEN+1 ou SCC_USER_SIZE, qui inclut de l’espace pour le terminateur Null).
Remarque
La première action que l’IDE peut être nécessaire pour effectuer peut être un appel à la SccOpenProject fonction ou à SccGetProjPath. Pour cette raison, les deux ont un paramètre identique lpUser .
lpAuxProjPath et lpProjName sont lus à partir du fichier solution, ou ils sont retournés à partir d’un appel à la SccGetProjPath fonction. Ces paramètres contiennent les chaînes que le plug-in de contrôle de code source associe au projet et sont significatifs uniquement pour le plug-in. Si aucune de ces chaînes ne se trouve dans le fichier solution et que l’utilisateur n’a pas été invité à parcourir (ce qui renvoie une chaîne via la SccGetProjPath fonction), l’IDE transmet des chaînes vides pour les deux lpAuxProjPath et lpProjNameattend que ces valeurs soient mises à jour par le plug-in lorsque cette fonction retourne.
lpTextOutProc est un pointeur vers une fonction de rappel fournie par l’IDE vers le plug-in de contrôle de code source pour afficher la sortie du résultat de commande. Cette fonction de rappel est décrite en détail dans LPTEXTOUTPROC.
Remarque
Si le plug-in de contrôle de code source envisage de tirer parti de cela, il doit avoir défini l’indicateur SCC_CAP_TEXTOUT dans SccInitialize. Si cet indicateur n’a pas été défini, ou si l’IDE ne prend pas en charge cette fonctionnalité, lpTextOutProc sera NULL.
Le dwFlags paramètre contrôle le résultat dans l’événement où le projet ouvert n’existe pas actuellement. Il se compose de deux flocons de bits, SCC_OP_CREATEIFNEW et SCC_OP_SILENTOPEN. Si le projet ouvert existe déjà, la fonction ouvre simplement le projet et retourne SCC_OK. Si le projet n’existe pas et si l’indicateur SCC_OP_CREATEIFNEW est activé, le plug-in de contrôle de code source peut créer le projet dans le système de contrôle de code source, l’ouvrir et le retourner SCC_OK. Si le projet n’existe pas et si l’indicateur SCC_OP_CREATEIFNEW est désactivé, le plug-in doit ensuite vérifier l’indicateur SCC_OP_SILENTOPEN . Si cet indicateur n’est pas activé, le plug-in peut inviter l’utilisateur à entrer un nom de projet. Si cet indicateur est activé, le plug-in doit simplement retourner SCC_E_UNKNOWNPROJECT.
Ordre d’appel
Dans le cours normal des événements, sccInitialize est appelé en premier pour ouvrir une session de contrôle de code source. Une session peut se composer d’un appel à SccOpenProject, suivi d’autres appels de fonction API plug-in de contrôle de code source, et se termine par un appel au SccCloseProject. Ces sessions peuvent être répétées plusieurs fois avant l’appel de SccUninitialize .
Si le plug-in de contrôle de code source définit le SCC_CAP_REENTRANT bit dans SccInitialize, la séquence de session ci-dessus peut être répétée plusieurs fois en parallèle. Différentes pvContext structures effectuent le suivi des différentes sessions, dans lesquelles chacune pvContext est associée à un projet ouvert à la fois. En fonction du pvContext paramètre, le plug-in peut déterminer quel projet est référencé dans n’importe quel appel particulier. Si le bit SCC_CAP_REENTRANT de fonctionnalité n’est pas défini, les plug-ins de contrôle de code source non réentrants sont limités dans leur capacité à travailler avec plusieurs projets.
Remarque
Le SCC_CAP_REENTRANT bit a été introduit dans la version 1.1 de l’API plug-in de contrôle de code source. Il n’est pas défini ou n’est pas ignoré dans la version 1.0, et tous les plug-ins de contrôle de code source version 1.0 sont supposés être non réentrants.