Fonction RasDialA (ras.h)

Article
08/25/2023

La fonction RasDial établit une connexion RAS entre un client RAS et un serveur RAS. Les données de connexion incluent des informations de rappel et d’authentification utilisateur.

Syntaxe

DWORD RasDialA(
  [in]  LPRASDIALEXTENSIONS unnamedParam1,
  [in]  LPCSTR              unnamedParam2,
  [in]  LPRASDIALPARAMSA    unnamedParam3,
  [in]  DWORD               unnamedParam4,
  [in]  LPVOID              unnamedParam5,
  [out] LPHRASCONN          unnamedParam6
);

Paramètres

[in] unnamedParam1

Pointeur vers une structure RASDIALEXTENSIONS qui spécifie un ensemble de fonctionnalités étendues RasDial à activer. Définissez ce paramètre sur NULL s’il n’est pas nécessaire d’activer ces fonctionnalités.

[in] unnamedParam2

Pointeur vers une chaîne terminée par null qui spécifie le chemin d’accès complet et le nom de fichier d’un fichier d’annuaire téléphonique (PBK). Si ce paramètre a la valeur NULL, la fonction utilise le fichier d’annuaire téléphonique par défaut actuel. Le fichier d’annuaire téléphonique par défaut est celui sélectionné par l’utilisateur dans la feuille de propriétés Préférences utilisateur de la boîte de dialogue Accès réseau à distance.

[in] unnamedParam3

Pointeur vers une structure RASDIALPARAMS qui spécifie les paramètres d’appel pour la connexion RAS. Utilisez la fonction RasGetEntryDialParams pour récupérer une copie de cette structure pour une entrée de téléphone particulière.

L’appelant doit définir le membre dwSize de la structure RASDIALPARAMS sur sizeof (RASDIALPARAMS) pour identifier la version de la structure transmise.

Si le membre szPhoneNumber de la structure RASDIALPARAMS est une chaîne vide, RasDial utilise le numéro de téléphone stocké dans l’entrée de l’annuaire téléphonique.

[in] unnamedParam4

Spécifie la nature du paramètre lpvNotifier . Si lpvNotifier a la valeur NULL, dwNotifierType est ignoré. Si lpvNotifier n’a pas la valeur NULL, définissez dwNotifierType sur l’une des valeurs suivantes.

Valeur	Signification
0	Le paramètre lpvNotifier pointe vers une fonction de rappel RasDialFunc .
1	Le paramètre lpvNotifier pointe vers une fonction de rappel RasDialFunc1 .
2	Le paramètre lpvNotifier pointe vers une fonction de rappel RasDialFunc2 .

[in] unnamedParam5

Spécifie un handle de fenêtre ou une fonction de rappel RasDialFunc , RasDialFunc1 ou RasDialFunc2 pour recevoir des notifications d’événements RasDial. Le paramètre dwNotifierType spécifie la nature de lpvNotifier. Pour plus d’informations, reportez-vous à la description précédente.

Si ce paramètre n’est pas NULL, RasDial envoie un message à la fenêtre ou appelle la fonction de rappel pour chaque événement RasDial . En outre, l’appel RasDial fonctionne de manière asynchrone : RasDial retourne immédiatement, avant l’établissement de la connexion, et communique sa progression via la fenêtre ou la fonction de rappel.

Si lpvNotifier a la valeur NULL, l’appel RasDial fonctionne de manière synchrone : RasDial ne retourne pas tant que la tentative de connexion n’a pas réussi ou échoué.

Si lpvNotifier n’a pas la valeur NULL, des notifications à la fenêtre ou à la fonction de rappel peuvent se produire à tout moment après l’appel initial à RasDial. Les notifications se terminent lorsqu’un des événements suivants se produit :

La connexion est établie. En d’autres termes, l’état de connexion RAS est RASCS_Connected.
La connexion échoue. En d’autres termes, dwError est différent de zéro.
RasHangUp est appelé sur la connexion.

Les notifications de rappel sont effectuées dans le contexte d’un thread capturé lors de l’appel initial à RasDial.

[out] unnamedParam6

Pointeur vers une variable de type HRASCONN. Définissez la variable HRASCONN sur NULL avant d’appeler RasDial. Si RasDial réussit, il stocke un handle à la connexion RAS dans *lphRasConn.

Valeur retournée

Si la fonction réussit, la valeur de retour est ERROR_SUCCESS et un handle à la connexion RAS est retourné dans la variable pointée par lphRasConn.

Si la fonction échoue, la valeur de retour provient des codes d’erreur de routage et d’accès à distance ou winerror.h.

Notes

Les erreurs qui se produisent après le retour immédiat peuvent être détectées par RasGetConnectStatus. Les données sont disponibles jusqu’à ce qu’une application appelle RasHangUp pour raccrocher la connexion.

Une application doit éventuellement appeler RasHangUp chaque fois qu’un handle de connexion non NULL est stocké dans *lphRasConn. Cela s’applique même si RasDial retourne une valeur différente de zéro (erreur).

Une application peut appeler RasHangUp en toute sécurité à partir d’une fonction de rappel de notification RasDial . Si cette opération est effectuée, toutefois, le raccrochage ne se produit pas tant que la routine n’est pas retournée.

Si la structure pointée vers lpRasDialExtensions active RDEOPT_PausedStates, la fonction RasDial s’interrompt chaque fois qu’elle entre dans un état dans lequel le RASCS_PAUSED bit est défini sur un. Pour redémarrer RasDial à partir d’un tel état suspendu, appelez à nouveau RasDial , en passant le handle de connexion retourné par l’appel RasDial d’origine dans *lphRasConn. Le même notifiant que celui utilisé dans l’appel RasDial d’origine doit être utilisé lors du redémarrage à partir d’un état suspendu.

Le paramètre lpvNotifier est un handle vers une fenêtre pour recevoir des messages de notification de progression. Dans un message de notification de progression, wParam est l’équivalent du paramètre rasconnstate de RasDialFunc et RasDialFunc1, et lParam est l’équivalent du paramètre dwError de RasDialFunc et RasDialFunc1.

Le message de notification de progression utilise un code de message inscrit par le système. Vous pouvez obtenir la valeur de ce code de message comme suit :

UINT unMsg = RegisterWindowMessageA( RASDIALEVENT );
if (unMsg == 0)
    unMsg = WM_RASDIALEVENT;

RAS prend en charge les connexions référencées. Si l’entrée en cours de numérotation est déjà connectée, RasDial retourne SUCCESS et la connexion est référencée. Pour déconnecter la connexion, chaque RasDial sur la connexion doit être mis en correspondance par un RasHangUp.

Étant donné que certaines entrées d’annuaire téléphonique nécessitent le protocole EAP (Extensible Authentication Protocol) pour l’authentification, l’appelant doit appeler RasGetEapUserIdentity avant d’appeler RasDial. Si RasGetEapUserIdentity retourne ERROR_INVALID_FUNCTION_FOR_ENTRY, l’entrée du carnet de téléphone ne nécessite pas EAP. Toutefois, si RasGetEapUserIdentity retourne NO_ERROR, l’appelant doit copier les informations d’identité EAP de RasGetEapUserIdentity dans le membre RasEapInfo de RASDIALEXTENSIONS et le membre szUserName de RASDIALPARAMS. Pour plus d’informations, consultez RasGetEapUserIdentity . Si l’entrée de l’annuaire téléphonique nécessite EAP, le membre dwfOptions de la structure RASENTRY de l’entrée contient l’indicateur RASEO_RequireEAP .

Pour spécifier que RasDial doit entrer un état RASCS_CallbackSetByCaller, définissez lpRasDialParams-szCallbackNumber> sur « * » lors de l’appel initial à RasDial. Lorsque le gestionnaire de notifications est appelé avec cet état, définissez le numéro de rappel sur un numéro fourni par l’utilisateur.

Notes

L’en-tête ras.h définit RasDial comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	ras.h
Bibliothèque	Rasapi32.lib
DLL	Rasapi32.dll