RasDialA, fonction (ras.h)

Article
11/20/2024

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 PBK (Phone-Book). Si ce paramètre est NULL, la fonction utilise le fichier de livre téléphonique par défaut actuel. Le fichier de carnet 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 Mise en réseau rendez-vous.

[in] unnamedParam3

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

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

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

[in] unnamedParam4

Spécifie la nature du paramètre lpvNotifier . Si lpvNotifier est NULL, dwNotifierType est ignoré. Si lpvNotifier n’est pas 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 un rasDialFunc, RasDialFunc1ou fonction de rappel RasDialFunc2 pour recevoir notifications d’événements RasDial. Le paramètre dwNotifierType spécifie la nature de lpvNotifier. Reportez-vous à sa description précédente pour plus de détails.

Si ce paramètre n’est pas null, RasDial envoie à la fenêtre un message ou appelle la fonction de rappel pour chaque événement RasDial 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 est 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’est pas NULL, les notifications à la fenêtre ou à la fonction de rappel peuvent se produire à tout moment après l’appel initial à RasDial . Les notifications se terminent quand l’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 n’est pas 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 sur la connexion RAS dans *lphRasConn.

Valeur de retour

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 de codes d’erreur de routage et d’accès à distance ou Winerror.h.

Remarques

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 nullnon-est stocké dans *lphRasConn. Cela s’applique même si rasDial retourne une valeur différente de zéro (erreur).

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

Si la structure pointée par lpRasDialExtensions active RDEOPT_PausedStates, la fonction RasDial s’interrompt chaque fois qu’elle entre dans un état dans lequel le bit RASCS_PAUSED est défini sur un. Pour redémarrer RasDial à partir d’un tel état suspendu, appelez RasDial, en passant à nouveau le handle de connexion retourné à partir de l’appel RasDial d’origine dans *lphRasConn. Le même notificateur utilisé dans le RasDial d’origine appel 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 enregistré 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 de carnet téléphonique nécessitent un 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 de carnet téléphonique 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 carnet de téléphone nécessite EAP, la dwfOptions membre de la structure RASENTRY pour l’entrée contient l’indicateur de RASEO_RequireEAP.

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

Note

L’en-tête ras.h définit RasDial comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	ras.h
bibliothèque	Rasapi32.lib
DLL	Rasapi32.dll