Appel dans Excel à partir de DLL ou XLL (traduction automatique)

Article
09/24/2014

Dernière modification : mercredi 31 mars 2010

S’applique à : Excel 2010 | Office 2010 | VBA | Visual Studio

Dans cet article
Excel4, Excel4v, Excel12 et fonctions Excel12v
Renvoyer la valeur XLOPER/XLOPER12 : operRes
Nombre d'Arguments suivants : nombre
Passage d'Arguments aux fonctions API C
XLCallVer

Important

Cet article a été traduit automatiquement, voir l’avertissement. Vous pouvez consulter la version en anglais de cet article ici.

Microsoft Excel permet à votre DLL d’accéder aux fonctions de feuille macro, aux fonctions de feuille de calcul et aux commandes Excel intégrées. Ces accès sont disponibles à partir de fonctions et commandes DLL appelées depuis Visual Basic for Applications (VBA), et à partir de fonctions et commandes XLL enregistrées appelées directement par Excel.

Excel4, Excel4v, Excel12 et fonctions Excel12v

Excel permet à votre DLL accéder aux commandes et fonctions par l'intermédiaire de la Excel4 des fonctions de rappel, la Excel4v, Excel12 et Excel12v.

Les fonctions Excel4 et Excel4v ont été introduites dans Excel version 4. Ils fonctionnent avec la structure de données XLOPER. Excel 2007 a introduit deux nouvelles fonctions de rappel, Excel12 et Excel12v, qui fonctionnent avec la structure de données XLOPER12. Les fonctions Excel4 et Excel4v sont exportées par la bibliothèque de Xlcall32.lib, qui doit être inclus dans votre projet de DLL ou XLL. Excel12 et Excel12v sont inclus dans le fichier de code source C++ du kit SDK Xlcall.cpp, qui doivent figurer dans votre projet si vous souhaitez accéder aux fonctionnalités d'Excel à l'aide de structures XLOPER12.

Le code suivant illustre les prototypes de fonction pour ces quatre fonctions. Les trois premiers arguments sont identiques à ceci près que le second argument est un pointeur vers un XLOPER dans la première paire et un pointeur vers un XLOPER12 dans la seconde paire. La convention d'appel est _cdecl dans Excel4 et Excel12 pour autoriser les listes d'arguments variable. Les points de suspension représente des pointeurs vers les valeurs de XLOPER pour Excel4 et XLOPER12 pour Excel12. Le nombre de pointeurs est égal à la valeur du paramètre count.

Toutes les versions d'Excel

int _cdecl Excel4(int xlfn, LPXLOPER operRes, int count,... );

int pascal Excel4v(int xlfn, LPXLOPER operRes, int count, LPXLOPER opers[]);

Démarrage en Excel 2007

int _cdecl Excel12(int xlfn, LPXLOPER12 operRes, int count,... );

int pascal Excel12v(int xlfn, LPXLOPER12 operRes, int count, LPXLOPER12 opers[]);

Pour la DLL être en mesure d'appeler Excel4, Excel4v, Excel12 ou Excel12v, Excel doit transmettre le contrôle à la DLL. Cela signifie que ces rappels API C peuvent être appelées uniquement dans les scénarios suivants :

À partir d'une commande XLL Excel a appelé directement ou par l'intermédiaire de VBA.
À partir au sein d'une fonction de feuille feuille de calcul ou une macro XLL qu'Excel a appelé directement ou par l'intermédiaire de VBA.

Vous ne pouvez pas appeler l'API C Excel dans les scénarios suivants :

À partir d'un événement de système d'exploitation (par exemple, à partir de la fonction DllMain (éventuellement en anglais)).
À partir d'un thread d'arrière-plan qui a créé votre DLL.

Valeurs de retour

Les quatre de ces fonctions renvoient une valeur entière qui indique si la fonction ou la commande a été appelée avec succès à l'appelant. Les valeurs renvoyées peuvent être une des opérations suivantes :

Valeur renvoyée	Défini dans Xlcall.h en tant que	Description
: {0}	xlretSuccess	La fonction ou la commande a été exécutée. Cela ne signifie pas que l'exécution a été sans erreur. Par exemple, Excel4 pourrait retourner xlretSuccess lors de l'appel de la fonction FIND, même si elle évaluée à #VALUE! dans la mesure où le texte recherché est introuvable. Vous devez examiner le type et la valeur de la XLOPER/XLOPER12 renvoyée dans le cas où cela est possible.
{1}	xlretAbort	Une macro de commande a été arrêtée par l'utilisateur en cliquant sur le bouton Annuler ou en appuyant sur la touche ÉCHAP.
{2}	xlretInvXlfn	Le code de commande ou de fonction fournie n'est pas valide. Cette erreur peut se produire lorsque la fonction d'appel n'est pas autorisé à appeler la fonction ou la commande. Par exemple, une fonction de feuille de calcul ne peut pas appeler une fonction d'informations de feuille macro ou une fonction de commande.
4	xlretInvCount	Le nombre d'arguments fournis dans l'appel n'est pas correct.
8	xlretInvXloper	Une ou plusieurs des valeurs d'argument XLOPER ou XLOPER12 ne sont pas correctement formés ou rempli.
16	xlretStackOvfl	Excel a détecté un risque que l'opération risque de dépassement de capacité sa pile et, par conséquent, n'a pas appelé la fonction.
32	xlretFailed	La commande ou la fonction a échoué pour une raison non décrite par parmi les autres valeurs de retour. Par exemple, une opération qui nécessiterait trop de mémoire, échouerait avec cette erreur. Cela peut se produire lors d'une tentative pour convertir une référence à un tableau xltypeMulti très volumineuse en utilisant la fonction xlCoerce.
64	xlretUncalced	L'opération a tenté de récupérer la valeur d'une cellule non calculée. Pour préserver l'intégrité de recalcul dans Excel, les fonctions de feuille de calcul ne sont pas autorisées pour ce faire. Toutefois, fonctions et commandes XLL inscrit comme fonctions de feuille de macro sont autorisées à accéder aux valeurs des cellules non calculées.
128	xlretNotThreadSafe	(À partir Excel 2007) Une fonction de feuille de calcul XLL inscrite en tant que thread-safe a tenté d'appeler une fonction API C qui n'est pas thread-safe. Par exemple, une fonction de thread-safe ne peut pas appeler la xlfGetCell de fonction XLM.
256	xlRetInvAsynchronousContext	(À partir Excel 2010) La poignée de la fonction asynchrone n'est pas valide.
512	xlretNotClusterSafe	(À partir Excel 2010) L'appel n'est pas pris en charge sur les clusters.

Si la fonction renvoie une des valeurs de l'échec de la table (en d'autres termes, elle ne retourne pas xlretSuccess), le XLOPER ou XLOPER12 renvoyer la valeur sera également définie à #VALUE!. Dans certaines circonstances, cette vérification peut être un test suffisant de succès, mais vous devez noter qu'un appel peut revenir à la fois xlretSuccess et #VALUE!.

Si un appel à l'API c entraîne xlretUncalced ou xlretAbort, votre code DLL ou XLL doit rendre le contrôle vers Excel avant d'effectuer tous les autres appels API C (autres que les appels à la fonction xlfree pour libérer les ressources de mémoire allouée Excel dans les valeurs XLOPER et XLOPER12).

Commande ou fonction énumération Argument : xlfn

L'argument xlfn est le premier argument au rappel fonctionne et est un entier signé 32 bits. Sa valeur doit être une des énumérations de fonction ou une commande définies dans le fichier d'en-tête SDK Xlcall.h, comme illustré dans l'exemple suivant.

// Excel function numbers. 
#define xlfCount 0
#define xlfIsna 2
#define xlfIserror 3
#define xlfSum 4
#define xlfAverage 5
#define xlfMin 6
#define xlfMax 7
#define xlfRow 8
#define xlfColumn 9
#define xlfNa 10
...

// Excel command numbers. 
#define xlcBeep (0 | xlCommand)
#define xlcOpen (1 | xlCommand)
#define xlcOpenLinks (2 | xlCommand)
#define xlcCloseAll (3 | xlCommand)
#define xlcSave (4 | xlCommand)
#define xlcSaveAs (5 | xlCommand)
#define xlcFileDelete (6 | xlCommand)
#define xlcPageSetup (7 | xlCommand)
#define xlcPrint (8 | xlCommand)
#define xlcPrinterSetup (9 | xlCommand)
...

Feuille de feuille de calcul et de la macro toutes les fonctions se trouvent dans la plage comprise entre 0 (xlfCount) et 0x0fff hexadécimal, bien que la plus élevée associée à numéro dans Excel 2010 est 547 décimal, 0x0223 hexadécimal (xlfFloor_precise).

Toutes les fonctions de commande sont comprises entre 0 x 8000 hexadécimal (xlcBeep) via 0x8fff hexadécimal, bien qu'il soit le plus élevé attribué en 2010 Excel 0x8328 hexadécimal (xlcHideallInkannots). Celles-ci sont définies dans le fichier d'en-tête comme (n | xlCommand) où n est un nombre entier supérieur ou égal à 0 et xlCommand est définie comme 0 x 8000 hexadécimal.

Appeler des commandes d'Excel qui utilisent des boîtes de dialogue

Certains des codes de commande correspondent aux actions dans Excel qui utilisent des boîtes de dialogue. Par exemple, xlcFileDelete accepte un argument unique : un nom de fichier ou un masque. Cela peut être appelée avec la boîte de dialogue afin que l'utilisateur a la possibilité d'annuler ou de modifier l'opération de suppression. Elle peut également être appelée sans la boîte de dialogue, auquel cas l'ou les fichiers sont supprimés sans aucune intervention supplémentaire, en supposant qu'ils existent et l'appelant est autorisé. Pour appeler ces commandes dans leur formulaire de boîte de dialogue, l'énumération de commande doit être combinée avec 0 x 1000 (xlPrompt) à l'aide de l'opération de bits OR.

L'exemple de code suivant supprime les fichiers dans le répertoire actif correspondant à la my_data*.bak de masque, afficher une boîte de dialogue uniquement si l'argument a la valeur true.

bool delete_my_backup_files(bool show_dialog)
{
    XLOPER12 xResult, xFilter;
    xFilter.xltype = xltypeStr;
    xFilter.val.str = L"\014my_data*.bak"; // String length: 14 octal
    int cmd;

    if(show_dialog)
        cmd = xlcFileDelete | xlPrompt;
    else
        cmd = xlcFileDelete;

// xResult should be Boolean TRUE if successful, in which
// case return true; otherwise, false.
    return (Excel12(cmd, &xResult, 1, &xFilter) == xlretSuccess
        && xResult.xltype == xltypeBool
        && xResult.val.xbool == 1);
}

Appel de fonctions et commandes dans les Versions internationales

Vous pouvez configurer Excel pour afficher les fonctions et les noms de commandes XLM dans une variété de langues. Certaines commandes API C et les fonctions fonctionnent sur les chaînes sont interprétées comme des noms de fonction ou une commande. Par exemple, xlcFormula prend un argument de chaîne qui est destiné à être placé dans une cellule spécifiée. Pour votre complément travailler avec tous les paramètres de langue, vous pouvez fournir les noms de chaîne en anglais et définir le bit 0 x 2000 (xlIntl) dans l'énumération de fonction ou une commande.

L'exemple de code suivant place l'équivalent de =SUM(X1:X100) dans la cellule A2 dans la feuille active. Notez qu'il utilise la fonction de la structure TempActiveRef, pour créer une XLOPER temporaire de référence externe. La formule s'affiche dans la cellule A2 dans la langue correcte déterminé de paramètres régionaux (par exemple, =SOMME(X1:X100) si la langue est le français).

int WINAPI InternationlExample(void)
{
    XLOPER12 xSum, xResult;
    xSum.xltype = xltypeStr;
    xSum.val.str = L"\015=SUM(X1:X100)";
    Excel12(xlcFormula | xlIntl, &xResult, 2,
        &xSum, TempActiveRef(2,2,1,1));
    return 1;
}

Notes

Le résultat de l'appel à Excel12 n'est pas indispensable et zéro (NULL) peut être passé comme deuxième argument au lieu de l'adresse de xResult. Ce point est traité plus dans la section suivante.

Commandes et fonctions DLL uniquement

Excel prend en charge un petit nombre de fonctions qui ne sont accessibles à partir d'une DLL ou XLL. Celles-ci sont définies dans le fichier d'en-tête comme (n | xlSpecial) où n est un nombre entier supérieur ou égal à 0 et xlSpecial est définie comme 0 x 4000 hexadécimal. Ces fonctions sont répertoriées dans le tableau suivant et documentées dans le Référence des fonctions API (traduction automatique).

xlFree (traduction automatique)	0 \| xlSpecial	Libère les ressources de mémoire allouée par Excel.
xlStack (traduction automatique)	1 \| xlSpecial	Retourne l'espace libre sur la pile d'Excel.
xlCoerce (traduction automatique)	2 \| xlSpecial	Effectue une conversion entre types XLOPER et XLOPER12
xlSet (traduction automatique)	3 \| xlSpecial	Fournit une méthode rapide de la définition de valeurs de cellule.
xlSheetId (traduction automatique)	4 \| xlSpecial	Obtient un nom de feuille de calcul à partir de son code interne.
xlSheetNm (traduction automatique)	5 \| xlSpecial	Obtient un ID interne de feuille de calcul à partir de son nom.
xlAbort (traduction automatique)	6 \| xlSpecial	Vérifie si l'utilisateur a cliqué sur le bouton Annuler ou appuyez sur la touche ÉCHAP.
xlGetInst (traduction automatique)	7 \| xlSpecial	Obtient le handle d'instance Excel.
xlGetHwnd (traduction automatique)	8 \| xlSpecial	Obtient le handle de fenêtre principale d'Excel.
xlGetName (traduction automatique)	9 \| xlSpecial	Obtient le chemin d'accès et le nom de la DLL.
xlEnableXLMsgs (traduction automatique)	10 \| xlSpecial	Cette fonction est obsolète. Il n’est plus nécessaire de l’appeler.
xlDisableXLMsgs (traduction automatique)	11 \| xlSpecial	Cette fonction est obsolète. Il n’est plus nécessaire de l’appeler.
xlDefineBinaryName (traduction automatique)	12 \| xlSpecial	Définit un nom d'un stockage persistant binaire.
xlGetBinaryName (traduction automatique)	13 \| xlSpecial	Obtient les données d'un nom un stockage persistant binaire.

Renvoyer la valeur XLOPER/XLOPER12 : operRes

L'argument operRes est le deuxième argument pour les rappels et est un pointeur vers un XLOPER (Excel4 et Excel4v) ou XLOPER12 (Excel12 et Excel12v). Après un appel réussi, il contient la valeur de retour de la fonction ou la commande. operRes peut être définie à zéro (pointeur NULL) si aucune valeur de retour n'est requis. Le contenu précédent du operRes est remplacé afin que toute mémoire pointé précédemment doit être libérée avant l'appel à éviter les fuites de mémoire.

Si la fonction ou la commande ne peut pas être appelé (par exemple, si les arguments sont incorrects), operRes est définie sur l'erreur #VALUE!. Une commande retourne toujours BooleanTRUE si l'opération a réussi, ou FALSE si elle a échoué ou l'utilisateur annulé.

Nombre d'Arguments suivants : nombre

L'argument count est le troisième argument pour les rappels et un entier signé 32 bits. Il doit indiquer le nombre d'arguments suivantes, en partant de 1. Si une fonction ou une commande ne prend aucun argument, elle doit être définie à zéro. Dans Microsoft Office Excel 2003, le nombre maximal d'arguments que n'importe quelle fonction peut prendre est de 30, bien que la plupart prennent moins de cela. À partir de Excel 2007, le nombre maximal d'arguments que n'importe quelle fonction peut prendre a été augmenté à 255.

Excel4 et Excel12, count correspond au nombre de pointeurs vers les valeurs XLOPER ou XLOPER12 qui sont passées. Soyez très prudent ne pas à passer moins d'arguments que la valeur que count a la valeur. Cela aurait pour résultat dans Excel en lecture à l'avance dans la pile et du traitement de XLOPER non valide ou valeurs XLOPER12, qui pourraient provoquer une panne de l'application.

Avec Excel4v et Excel12v, count est la taille du tableau de pointeurs vers les valeurs XLOPER ou XLOPER12 qui est passée comme argument final et suivant. Là encore, vous devez être très prudent ne pas à transmettre un tableau plus petit que celui des éléments count taille, car ceci se traduira dans les limites du tableau surchargé.

Passage d'Arguments aux fonctions API C

Excel4 et Excel12 prennent de longueur variable listes d'arguments, après count, qui sont interprétées comme des pointeurs vers les valeurs XLOPER et XLOPER12, respectivement. Excel4v et Excel12v prennent un argument unique, après count, qui est un pointeur vers un tableau de pointeurs aux valeurs XLOPER dans le cas de Excel4v et XLOPER12 les valeurs de le Excel12v.

Les formulaires de tableau, des Excel4v et Excel12v, permettent de coder un appel à l'API c proprement lorsque le nombre d'arguments est variable. L'exemple suivant montre une fonction qui prend un tableau de taille variable de chiffres et utilise les fonctions de feuille de calcul Excel, via l'API C, pour calculer la somme, moyenne, minimale et maximale.

void Excel12v_example(double *dbl_array, int size, double &sum, double &average, double &min, double &max)
{
// 30 is the limit in Excel 2003. 255 is the limit in Excel 2007.
// Use the lower limit to be safe, although it is better to make
// the function version-aware and use the correct limit.
    if(size < 1 || size > 30)
        return;

// Create an array of XLOPER12 values.
    XLOPER12 *xOpArray = (XLOPER12 *)malloc(size * sizeof(XLOPER12));
// Create an array of pointers to XLOPER12 values.
    LPXLOPER12 *xPtrArray =
        (LPXLOPER12 *)malloc(size * sizeof(LPXLOPER12));

// Initialize and populate the array of XLOPER12 values
// and set up the pointers in the pointer array.
    for(int i = 0; i < size; i++)
    {
        xOpArray[i].xltype = xltypeNum;
        xOpArray[i].val.num = dbl_array[i];
        xPtrArray[i] = xOpArray + i;
    }

    XLOPER12 xResult;
    int retval;
    int fn[4] = {xlfSum, xlfAverage, xlfMin, xlfMax};
    double *result_ptr[4] = {&sum, &average, &min, &max};

    for(i = 0; i < 4; i++)
    {
        retval = Excel12v(fn[i], &xResult, size, xPtrArray);
        if(retval == xlretSuccess && xResult.xltype == xltypeNum)
            *result_ptr[i] = xResult.val.num;
    }
    free(xPtrArray);
    free(xOpArray);
}

Remplaçant les références aux valeurs XLOPER12 avec XLOPER et Excel12v avec Excel4v, dans le code précédent aurait pour résultat dans une fonction qui fonctionne avec toutes les versions d'Excel. Cette opération des fonctions SUM, AVERAGE, MIN et MAX Excel est assez simple pour qu'il serait plus efficace de les coder dans c et éviter la surcharge de préparer les arguments et d'appel dans Excel. Toutefois, la plupart des fonctions Qu'excel contient sont plus complexes, en rendant cette approche est utile dans certains cas.

La rubrique xlfRegister fournit un autre exemple de l'utilisation de Excel4v et Excel12v. Lorsque vous enregistrez une fonction de feuille de calcul XLL, vous pouvez fournir une chaîne descriptive pour chaque argument est utilisé dans la boîte de dialogue Coller une fonction . Par conséquent, le nombre d'arguments total fourni à xlfRegister dépend du nombre d'arguments que prend votre fonction XLL et varie d'une fonction à l'autre.

Lorsque vous appelez toujours une fonction API C ou une commande avec le même nombre d'arguments, que vous voulez éviter l'étape supplémentaire de la création d'un tableau de pointeurs pour ces arguments. Dans ces cas, il est plus simple et plus propre à utiliser Excel4 et Excel12. Par exemple, lors de l'enregistrement des commandes et fonctions XLL, vous devez fournir le chemin d'accès et le nom complet de la DLL ou XLL. Vous pouvez obtenir le nom du fichier dans un appel à xlfGetName et libérer avec un appel à xlFree, comme illustré dans l'exemple suivant pour Excel4 et Excel12.

XLOPER xDllName;
if(Excel4(xlfGetName, &xDllName, 0) == xlretSuccess)
{
    // Use the name, and 
    // then free the memory that Excel allocated for the string.
    Excel4(xlFree, 0, 1, &xDllName);
}

XLOPER12 xDllName;
if(Excel12(xlfGetName, &xDllName, 0) == xlretSuccess)
{
    // Use the name, and
    // then free the memory that Excel allocated for the string.
    Excel12(xlFree, 0, 1, &xDllName);
}

Dans la pratique, la fonction, Excel12v_example, peut être codée plus efficacement en créant un argument unique xltypeMultiXLOPER12 et en appelant l'API c à l'aide de Excel12, comme illustré dans l'exemple suivant.

void Excel12_example(double *dbl_array, int size, double &sum, double &average, double &min, double &max)
{
// In this implementation, the upper limit is the largest
// single column array (equals 2^20, or 1048576, rows in Excel 2007).
    if(size < 1 || size > 1048576)
        return;

// Create an array of XLOPER12 values.
    XLOPER12 *xOpArray = (XLOPER12 *)malloc(size * sizeof(XLOPER12));

// Create and initialize an xltypeMulti array
// that represents a one-column array.
    XLOPER12 xOpMulti;
    xOpMulti.xltype = xltypeMulti;
    xOpMulti.val.array.lparray = xOpArray;
    xOpMulti.val.array.columns = 1;
    xOpMulti.val.array.rows = size;

// Initialize and populate the array of XLOPER12 values.
    for(int i = 0; i < size; i++)
    {
        xOpArray[i].xltype = xltypeNum;
        xOpArray[i].val.num = dbl_array[i];
    }

    XLOPER12 xResult;
    int fn[4] = {xlfSum, xlfAverage, xlfMin, xlfMax};
    double *result_ptr[4] = {&sum, &average, &min, &max};

    for(i = 0; i < 4; i++)
    {
        Excel12(fn[i], &xResult, 1, &xOpMulti);
        if(xResult.xltype == xltypeNum)
            *result_ptr[i] = xResult.val.num;
    }
    free(xOpArray);
}

Notes

Dans ce cas, la valeur de retour de Excel12 est ignorée. Le code vérifie à la place que le XLOPER12 retourné est xltypeNum pour déterminer si l'appel a réussi.

XLCallVer

En outre pour les rappels Excel4, Excel4v, Excel12 et Excel12v, Excel exporte une fonction XLCallVer, qui retourne la version de l'API c en cours d'exécution.

Le prototype de fonction se présente comme suit :

int pascal XLCallVer(void);

Vous pouvez appeler cette fonction, qui est thread-safe, à partir de toute commande XLL ou fonction.

Dans Excel 97 à Excel 2003, XLCallVer renvoie hex 1280 = 0 x 0500 = 5 x 256, qui indique à Excel version 5. À partir de Excel 2007, elle retourne 3072 = 0x0c00 hex = 12 x 256, qui indique de même version 12.

Bien que vous puissiez l'utiliser pour déterminer si la nouvelle API C est disponible au moment de l'exécution, vous pouvez préférer détecter la version en cours d'exécution d'Excel à l'aide de Excel4(xlfGetWorkspace, &version, 1, &arg), où arg est un XLOPER numérique la valeur 2. La fonction renvoie un XLOPER de chaîne, version, qui peut ensuite être convertie en un entier. La raison de s'appuyer sur la version d'Excel plutôt que la version de l'API c est qu'il existe des différences entre Excel 2000, Excel 2002 et Excel 2003 devant votre complément peut également détecter. Par exemple, les modifications ont été apportées à l'exactitude de certaines fonctions statistiques.

Notes

Avertissement traduction automatique : cet article a été traduit par un ordinateur, sans intervention humaine. Microsoft propose cette traduction automatique pour offrir aux personnes ne maîtrisant pas l’anglais l’accès au contenu relatif aux produits, services et technologies Microsoft. Comme cet article a été traduit automatiquement, il risque de contenir des erreurs de grammaire, de syntaxe ou de terminologie.