GetAppcConfig

  • Article

La fonction GetAppcConfig fournit un point d’entrée asynchrone pour récupérer les systèmes distants auxquels une lu locale particulière peut se connecter.

Syntaxe

  
HANDLE WINAPI GetAppcConfig(   
HANDLE hWnd,  
LPSTR pLocalLu,  
LPSTR pMode,  
LPINT pNumRemLu,  
INT iMaxRemLu,  
PSTR pRemLu,  
LPINT pAsyncRetCode  
);

Paramètres

hWnd
Paramètre fourni. Contient le handle de la fenêtre qui doit recevoir un message d’achèvement asynchrone une fois l’appel terminé. S’il n’est pas null, le message d’achèvement est publié dans ce handle de fenêtre. Dans ce cas, pAsyncRetCode (le dernier paramètre) doit avoir la valeur Null. L’achèvement asynchrone des messages est l’approche recommandée pour les applications Windows pour utiliser cette fonction.

pLocalLu
Paramètre fourni. Spécifie l’adresse d’une mémoire tampon contenant le nom de l’unité lu locale pour laquelle les informations sont retournées. Ce nom lu local doit être spécifié comme suit :

  • Non pavé

  • Terminé par null

  • Chaîne ASCII

  • Longueur maximale de huit octets (à l’exclusion de la terminaison)

    Pour demander l’utilisation de la lu locale par défaut de l’utilisateur, la mémoire tampon doit contenir huit espaces suivis d’une valeur Null.

    pMode
    Paramètre fourni. Spécifie l’adresse d’une mémoire tampon contenant le nom de mode pour lequel les informations sont retournées. Dans Microsoft Host Integration Server, ce paramètre n’est pas utilisé, mais pour la compatibilité avec les versions antérieures de SNA Server, un nom de mode doit être spécifié comme suit :

  • Non pavé

  • Terminé par null

  • Chaîne ASCII

  • Longueur maximale de huit octets (à l’exclusion de la terminaison)

    pNumRemLu
    Paramètre fourni. Spécifie l’adresse d’une variable entière qui, une fois la fonction terminée, contiendra le nombre de LU distantes qui auraient été retournées, si la mémoire tampon spécifiée par pRemLu était suffisamment grande pour prendre en charge toutes les unités LU distantes.

    iMaxRemLu
    Paramètre fourni. Spécifie le nombre de noms lu distants pouvant être conservés par la mémoire tampon indiquée par pRemLu.

    pRemLu
    Paramètre fourni. Spécifie l’adresse de la mémoire tampon qui contiendra les noms lu distants une fois la fonction terminée. Les informations seront retournées sous la forme d’un tableau de chaînes. Chaque nom lu distant est stocké dans la mémoire tampon comme suit :

  • Non pavé

  • Terminé par null

  • Chaîne ASCII

  • Longueur maximale de huit octets (à l’exclusion de la terminaison)

    Les chaînes commencent tous les neuf octets dans la mémoire tampon, et par conséquent (pRemLu + (i–1)*9) donne le début de la iième chaîne. Dans le cas où la mémoire tampon est trop petite pour contenir tous les noms, seules les chaînes iMaxRemLu sont retournées.

    pAsyncRetCode
    Paramètre fourni. Spécifie l’adresse d’une variable entière utilisée pour stocker le code de retour de cette fonction, si l’adresse fournie n’est pas null. Les codes de retour seront les mêmes que ceux retournés par un message d’achèvement asynchrone. Lorsque l’appel se termine, la valeur de cette variable est APPC_CFG_PENDING. Une fois cet appel asynchrone terminé, la valeur de cette variable contient du code de retour autre que APPC_CFG_PENDING.

    Cette variable est utilisée par l’interrogation de l’achèvement lorsque la saisie semi-automatique de message asynchrone dans un handle de fenêtre n’est pas utilisée.

    Notez que si pAsyncRetCode est utilisé, hWnd doit avoir la valeur Null.

Valeur renvoyée

La signification de la valeur de retour immédiat dépend de l’acceptation ou non de la demande asynchrone. Pour tester l’acceptation, évaluez l’expression :

(<Handle retourné> & APPC_CFG_SUCCESS)

Si l’expression a la valeur FALSE, la demande a été rejetée. La valeur de retour est alors l’un des codes de retour synchrones de la liste suivante. Si l’expression a la valeur TRUE, la demande a été acceptée et l’un des cas suivants s’applique.

  • Si hWnd n’était pas null, un message d’achèvement arrive sous la forme suivante :

    Paramètre de message Description
    hWnd Handle de la fenêtre cible. Cette valeur est identique à la valeur passée en hWnd lors de l’appel initial.
    uMsg Correspond au numéro retourné par un appel à RegisterWindowMessage, avec WinAppcCfg utilisé comme chaîne d’identification. Cette chaîne est disponible par le #define WIN_APPC_CFG_COMPLETION_MSG.
    wParam Correspond au HANDLE retourné à partir de l’appel initial. Il est utilisé comme corrélateur.
    lParam Contient l’un des codes de retour asynchrones de la liste suivante.

  • Si pAsyncRetCode n’était pas null, la variable entière spécifiée sera définie sur APPC_CFG_PENDING. Une fois cette fonction terminée de manière asynchrone, sa valeur passe à l’un des codes de retour asynchrones répertoriés ci-dessous.

Codes de retour synchrones

APPC_CFG_ERROR_NO_APPC_INIT
La bibliothèque Windows APPC doit être initialisée par un appel à WinAPPCStartup avant d’appeler GetAppcConfig , ce qui n’a pas été fait.

APPC_CFG_ERROR_INVALID_HWND
Le handle passé dans hWnd n’était pas null, mais pas un handle de fenêtre valide.

APPC_CFG_ERROR_BAD_POINTER
Le paramètre hWnd était null, ce qui indique que l’achèvement a été signalé en définissant la variable entière pointée vers pAsyncRetCode, mais pAsyncRetCode n’était pas un pointeur valide.

APPC_CFG_ERROR_UNCLEAR_COMPLETION_MODE
HWnd et pAsyncCompletion n’étant pas null, GetAppcConfig n’a pas pu décider de la façon dont l’achèvement doit être signalé.

APPC_CFG_ERROR_TOO_MANY_REQUESTS
Trop d’appels GetAppcConfig sont déjà traités (actuellement, cela indique que 16 demandes sont en attente). Réessayez l’appel après un délai. Pour Microsoft Windows version 3. x système, vous devez céder pendant cette période.

APPC_CFG_ERROR_GENERAL_FAILURE
Une erreur inattendue s’est produite, probablement de nature système.

Codes de retour asynchrones

APPC_CFG_SUCCESS_NO_DEFAULT_REMOTE
Les informations de configuration ont été récupérées et aucune lu distante par défaut n’a été définie ou elle n’était pas accessible par l’unité lu locale spécifiée.

APPC_CFG_SUCCESS_DEFAULT_REMOTE
Les informations de configuration ont été récupérées et il existe une lu distante par défaut accessible par la lu locale spécifiée.

APPC_CFG_ERROR_NO_DEFAULT_LOCAL_LU
Une tentative de récupération des unités lu distantes associées à l’unité lu locale par défaut a été effectuée, mais aucune lu locale par défaut n’a été configurée.

APPC_CFG_ERROR_BAD_LOCAL_LU
La lu locale spécifiée n’est pas configurée ou n’est pas valide pour le verbe appelant.

APPC_CFG_ERROR_GENERAL_FAILURE
Une erreur inattendue s’est produite, probablement de nature système.

Remarques

WinAPPCStartup doit être appelé avant d’utiliser GetAppcConfig.

Vous pouvez déterminer si un code d’erreur représente la réussite ou l’échec en évaluant (RetCode& APPC_CFG_SUCCESS) pour tester la réussite ou (RetCode& APPC_CFG_FAILURE) pour tester l’échec.

Le fragment de code suivant montre comment une application console peut tester l’achèvement :

while (*pAsyncRetCode == APPC_CFG_PENDING)  
{  
    sleep(250);  
}