xlfRegister (formulaire 1)
S’applique à: Excel 2013 | Office 2013 | Visual Studio
Peut être appelé à partir d’une commande DLL ou XLL qui a elle-même été appelée par Microsoft Excel. Cela équivaut à appeler REGISTER à partir d’une feuille macro Excel XLM.
xlfRegister peut être appelé sous deux formes :
xlfRegister (formulaire 1) : inscrit une seule commande ou fonction.
xlfRegister (Formulaire 2) : charge et active un XLL.
Appelée dans le formulaire 1, cette fonction met une fonction ou une commande DLL à la disposition d’Excel, définit son nombre d’utilisation sur 1 et retourne son ID d’inscription, qui peut être utilisé pour appeler la fonction ultérieurement à l’aide de la fonction xlUDF ou xlfCall . L’ID d’inscription est également utilisé pour annuler l’inscription de la fonction à l’aide de xlfUnregister (Formulaire 1). Si la fonction a été inscrite, l’appel de xlfRegister incrémente à nouveau son nombre d’utilisations.
Cette forme de la fonction définit également un nom masqué qui est l’argument texte de la fonction, pxFunctionText, et qui prend la valeur de l’ID d’inscription de la fonction ou de la commande. Lorsque vous annulez l’inscription de la fonction, supprimez ce nom en utilisant xlfSetName. Pour plus d’informations, reportez-vous à la rubrique Problèmes connus concernant le développement de XLL Excel.
Excel12(xlfRegister, LPXLOPER12 pxRes, int iCount,
LPXLOPER12 pxModuleText, LPXLOPER12 pxProcedure,
LPXLOPER12 pxTypeText, LPXLOPER12 pxFunctionText,
LPXLOPER12 pxArgumentText, LPXLOPER12 pxMacroType,
LPXLOPER12 pxCategory, LPXLOPER12 pxShortcutText,
LPXLOPER12 pxHelpTopic, LPXLOPER12 pxFunctionHelp,
LPXLOPER12 pxArgumentHelp1, LPXLOPER12 pxArgumentHelp2,
...);
Paramètres
pxModuleText (xltypeStr)
Nom de la DLL qui contient la fonction. Cela peut être obtenu en appelant la fonction XLL uniquement xlGetName si la fonction inscrite se trouve également dans la DLL en cours d’exécution.
pxProcedure (xltypeStr ou xltypeNum)
S’il s’agit d’une chaîne, le nom de la fonction à appeler tel qu’il apparaît dans le code DLL. Si un nombre, numéro d’exportation ordinal de la fonction à appeler. Pour plus de clarté, utilisez toujours la forme chaîne.
pxTypeText (xltypeStr)
Chaîne facultative qui spécifie les types d’arguments de la fonction et le type de la valeur de retour de la fonction. Pour plus d'informations, voir la section Notes. Cet argument peut être omis pour une DLL autonome (XLL) qui inclut une fonction xlAutoRegister ou xlAutoRegister12.
Remarque
xlAutoRegister12 est uniquement pris en charge dans Excel 2007.
Si xlfRegister est appelé avec cet argument manquant, Excel appelle xlAutoRegister ou xlAutoRegister12, s’il existe dans la DLL spécifiée, qui doit ensuite inscrire correctement la fonction en fournissant ces informations.
pxFunctionText (xltypeStr)
Nom de la fonction tel qu’il apparaîtra dans l’Assistant Fonction. Cet argument est facultatif ; si elle est omise, la fonction n’est pas disponible dans l’Assistant Fonction et peut uniquement être appelée à l’aide de la fonction CALL à l’aide de l’ID d’inscription des fonctions d’une feuille macro XLM. Par conséquent, pour une utilisation ordinaire de la feuille de calcul, vous devez gérer cet argument en fonction des besoins.
pxArgumentText (xltypeStr)
Chaîne de texte facultative qui décrit les arguments de la fonction. L’utilisateur le voit dans l’Assistant Fonction. S’il est omis, Excel construit des descriptions de base à partir de pxTypeText.
pxMacroType (xltypeNum ou xltypeInt)
Argument facultatif qui indique le type de point d’entrée XLL. La valeur par défaut, si elle est omise, est 1.
| valeur pxMacroType |
0 |
1 |
2 |
|---|---|---|---|
| Peut être appelé à partir d’une feuille de calcul |
Oui |
Oui |
Non |
| Peut être appelé à partir d’une feuille macro |
Oui |
Oui |
Oui |
| Peut être appelé à partir d’une définition de nom définie |
Oui |
Oui |
Oui |
| Peut être appelé à partir d’une expression de format conditionnel |
Oui |
Oui |
Non |
| Répertorié dans l’Assistant Fonction pour les fonctions de feuille de calcul |
Non |
Oui |
Non |
| Répertorié dans l’Assistant Fonction pour les fonctions de feuille de macro |
Non |
Oui |
Oui |
Dans la pratique, vous devez utiliser 1 pour les fonctions de feuille de calcul, 1 pour les fonctions équivalentes à la feuille de macro (inscrites en tant que type #) que vous souhaitez appeler à partir de la feuille de calcul et 2 pour les commandes.
Remarque
Les commandes XLL sont masquées et ne sont pas affichées dans les boîtes de dialogue pour l’exécution de macros, bien que leurs noms puissent être entrés partout où un nom de commande valide est requis.
pxCategory (xltypeStr ou xltypeNum)
Argument facultatif qui vous permet de spécifier la catégorie à laquelle la nouvelle fonction ou commande doit appartenir. L’Assistant Fonction divise les fonctions par type (catégorie). Vous pouvez spécifier un nom de catégorie ou un nombre séquentiel, où le numéro est la position dans laquelle la catégorie apparaît dans l’Assistant Fonction. Pour plus d’informations, consultez la section « Noms des catégories ». S’il est omis, la catégorie Définie par l’utilisateur est supposée.
pxShortcutText (xltypeStr)
Chaîne à un caractère respectant la casse qui spécifie la clé de contrôle affectée à cette commande. Par exemple, « A » affecte cette commande à CONTROL+MAJ+A. Cet argument est facultatif et est utilisé uniquement pour les commandes.
pxHelpTopic (xltypeStr)
Référence facultative au fichier d’aide (.chm ou .hlp) à afficher lorsque l’utilisateur clique sur le bouton Aide (lorsque votre fonction personnalisée s’affiche). Peut être au format filepath!HelpContextID ou https://address/path_to_file_in_site!0. Les deux parties avant et après le « ! » sont obligatoires. HelpContextID ne doit pas contenir de guillemets simples et sera converti par Excel en entier non signé de 4 octets, au format décimal. Lorsque vous utilisez le formulaire URL, Excel ouvre uniquement le fichier d’aide référencé.
pxFunctionHelp (xltypeStr)
Chaîne facultative qui décrit votre fonction personnalisée lorsqu’elle est sélectionnée dans l’Assistant Fonction.
pxArgumentHelp1 (xltypeStr)
Optional. La première des chaînes qui décrivent les arguments personnalisés de la fonction lorsque la fonction est sélectionnée dans l’Assistant Fonction. Dans Excel 2003 et les versions antérieures, xlfRegister peut prendre, au maximum, 30 arguments afin que vous puissiez fournir cette aide pour les 20 premiers arguments de fonction uniquement. À compter d’Excel 2007, xlfRegister peut prendre jusqu’à 255 arguments afin que vous puissiez fournir cette aide pour jusqu’à 245 paramètres de fonction.
Valeur de propriété/valeur de renvoi
Si l’inscription a réussi, cette fonction renvoie l’ID de registre de la fonction (xltypeNum), qui peut être utilisé dans les appels à xlUDF et xlfUnregister dans une DLL, ou avec CALL et UNREGISTER dans une feuille macro XLM. Sinon, il retourne une #VALUE ! Erreur.
Remarques
Types de données
L’argument pxTypeText spécifie le type de données de la valeur de retour et les types de données de tous les arguments de la fonction DLL ou de la ressource de code. Le premier caractère de pxTypeText spécifie le type de données de la valeur de retour. Les caractères restants indiquent les types de données de tous les arguments. Par exemple, une fonction DLL qui retourne un nombre à virgule flottante et prend un entier et un nombre à virgule flottante comme arguments nécessite « BIB » pour l’argument pxTypeText .
Les types de données et les structures utilisés par Excel pour échanger des données avec des XLL sont résumés dans les deux tableaux suivants.
Le premier tableau répertorie les types pris en charge dans toutes les versions d’Excel.
| Type de données | Passer par valeur | Passer par référence (pointeur) | Commentaires |
|---|---|---|---|
| Booléen |
A |
L |
short [int] (0=false ou 1=true) |
| double |
B |
E |
|
| char * |
C, F |
Chaîne d’octets ASCII se terminant par null |
|
| unsigned char * |
D, G |
Chaîne d’octets ASCII comptée |
|
| unsigned short [int] |
H |
WORD 16 bits |
|
| [signed] short [int] |
I |
M |
Entier signé 16 bits |
| [signed long] int |
J |
N |
Entier signé 32 bits |
| FP |
K |
Structure de tableau à virgule flottante |
|
| Tableau |
O |
Trois arguments sont passés : - unsigned short int * - unsigned short int * - double [] |
|
| XLOPER |
P |
Tableaux et valeurs de feuille de calcul de type variable |
|
| Valeur | R |
Valeurs, tableaux et références de plage |
Dans Excel 2007, les types de données suivants ont été introduits pour prendre en charge les grandes grilles et les chaînes Unicode longues.
| Type de données | Passer par valeur | Passer par référence (pointeur) | Commentaires |
|---|---|---|---|
| unsigned short * |
C%, F% |
Chaîne de caractères larges Unicode terminée par null |
|
| unsigned short * |
D%, G% |
Chaîne de caractères larges Unicode comptée |
|
| FP12 |
K% |
Structure de tableau à virgule flottante de grille plus grande |
|
| Tableau |
O% |
Trois arguments sont passés : - signed int * / RW * - signed int * / COL * - double [] |
|
| XLOPER12 |
Q |
Tableaux et valeurs de feuille de calcul de type variable |
|
| Valeur | U |
Valeurs, tableaux et références de plage |
À partir d’Excel 2010, les types de données suivants ont été introduits :
| Type de données | Passer par valeur | Passer par référence (pointeur) | Commentaires |
|---|---|---|---|
| XLOPER12 |
X |
Le handle asynchrone est utilisé pour suivre un appel de fonction asynchrone en attente par Excel et xlL. L’existence du type de paramètre dans la chaîne de type désigne également la fonction comme asynchrone. Pour plus d’informations sur les fonctions asynchrones, consultez Fonctions User-Defined asynchrones. |
Les types de chaînesF, F%, G et G% sont utilisés pour les arguments qui sont modifiés directement (modified-in-place).
Lorsque vous utilisez les types de données affichés dans le tableau précédent, tenez compte des éléments suivants :
- Les déclarations en langage C supposent que votre compilateur utilise par défaut des nombres doubles de 8 octets, des entiers courts de 2 octets et des entiers longs de 4 octets.
- Toutes les fonctions dans les DLL et les ressources de code sont appelées à l’aide de la convention d’appel __stdcall .
- Toute fonction qui retourne un type de données par référence, c’est-à-dire qui retourne un pointeur vers quelque chose, peut retourner un pointeur null en toute sécurité. Excel interprète un pointeur null comme un #NUM ! Erreur.
Informations supplémentaires sur le type de données
Cette section contient des informations détaillées sur les types de données E, F, F%, G, G%, K, O, P, Q, R et U , ainsi que d’autres informations sur l’argument pxTypeText .
Type de données E
Excel s’attend à ce qu’une DLL utilisant le type de données E passe des pointeurs vers des nombres à virgule flottante sur la pile. Cela peut entraîner des problèmes avec certains langages (par exemple, Borland C++) qui s’attendent à ce que le nombre soit transmis sur la pile de l’émulateur de coprocesseur. La solution de contournement consiste à passer un pointeur vers le nombre sur la pile du coprocesseur. L’exemple suivant montre comment retourner un double à partir de Borland C++.
typedef double * lpDbl;
extern "C" lpDbl __stdcall AddDbl(double D1,
double D2, WORD npDbl)
{
lpDbl Result;
Result = (lpDbl)MK_FP(_SS, npDbl);
*Result = D1 + D2;
return (Result);
}
Types de données F, F%, G et G%
Avec les types de données F, F%, G et G% , une fonction peut modifier une mémoire tampon de chaîne allouée par Excel. Si le code de type valeur de retour est l’un de ces types, Excel ignore la valeur retournée par la fonction. Au lieu de cela, Excel recherche dans la liste des arguments de fonction le premier type de données correspondant (F, F%, G ou G%), puis prend le contenu actuel de la mémoire tampon de chaîne allouée comme valeur de retour. Toutes les versions d’Excel allouent 256 octets pour les chaînes ASCII F et G, et à compter d’Excel 2007, 65 536 octets sont alloués, soit suffisamment pour 32 768 caractères Unicode, pour les chaînes Unicode F% et G%. N’oubliez pas que les mémoires tampons doivent inclure un caractère de comptage (types G et G%) ou un caractère d’arrêt Null (types F et F%), de sorte que les longueurs de chaîne maximales réelles sont de 255 et 32 767. Les chaînes Unicode, et donc les arguments de type F% et G% , sont disponibles uniquement via l’API C dans Excel.
Types de données K et K%
Les types de données K et K% utilisent des pointeurs vers les structures FP et FP12 de taille variable respectivement. Ces structures sont définies dans XLLCALL.H. Les structures FP12, et donc les arguments de type K% , ne sont prises en charge qu’à partir d’Excel 2007.
Types de données O et O%
Les types de données O et O% ne peuvent être utilisés que pour les arguments, et non pour les valeurs de retour, bien que les valeurs puissent être retournées en modifiant un argument de type O ou O% sur place. Chacun passe trois éléments : un pointeur vers le nombre de lignes dans un tableau, un pointeur vers le nombre de colonnes dans un tableau et un pointeur vers un tableau à deux dimensions de nombres à virgule flottante.
Pour modifier un tableau passé par le type de données O ou O% sur place, vous pouvez utiliser «> O » ou «> O% » comme argument pxTypeText . Pour plus d’informations sur la modification d’un tableau, consultez la section « Modification sur place : Fonctions déclarées comme Void » dans cette rubrique.
Le type de données O a été créé pour une compatibilité directe avec les DLL Fortran, qui passent des arguments par référence.
O % est pris en charge à partir d’Excel 2007 et prend en charge le plus grand nombre de lignes prises en charge par Excel.
Types de données P et Q
Lorsque les arguments de fonction DLL sont inscrits comme prenant le type P XLOPERs ou le type Q XLOPER12s, Excel convertit les références à cellule unique en valeurs simples et les références à plusieurs cellules en tableaux lors de la préparation de ces arguments. En d’autres termes, les types P et Q arrivent toujours dans votre fonction comme l’un des types suivants : xltypeNum, xltypeStr, xltypeBool, xltypeErr, xltypeMulti, xltypeMissing ou xltypeNil, mais pas xltypeRef ou xltypeSRef , car ils sont toujours déréférencés. XLOPER12, et donc les arguments de type Q , ne sont pris en charge qu’à partir d’Excel 2007.
Si les types xltypeMissing ou xltypeNil sont utilisés pour les valeurs de retour, ils sont interprétés par Excel comme zéro numérique. xltypeMissing est passé lorsque l’appelant omet un argument. xltypeNil est transmis lorsque l’appelant transmet une référence à une cellule vide. Lorsqu’une plage de cellules est convertie en xltypeMulti à passer en tant que type P ou Q, toutes les cellules vides de la plage sont converties en éléments de tableau xltypeNil . Les éléments manquants dans un tableau littéral sont également passés en tant qu’éléments xltypeNil .
Fonctions volatiles et recalcul
Dans une feuille de calcul, vous pouvez rendre une fonction DLL ou une ressource de code volatile, afin qu’elle recalcule chaque fois que la feuille de calcul est recalculée. Pour ce faire, ajoutez un point d’exclamation ( !) après le dernier code d’argument dans l’argument pxTypeText .
Remarque
Par défaut, les fonctions qui prennent le type R XLOPERs ou le type U XLOPER12s et qui sont inscrites en tant qu’équivalents de feuille de macro (type #; voir la section suivante) sont gérées comme volatiles dans Excel.
Fonctions déclarées comme void
Il existe deux cas qui appellent à déclarer une fonction comme retournant void. Dans les deux cas, la fonction retourne son résultat par d’autres moyens.
Modification sur place
Vous pouvez utiliser un seul chiffre n pour le code de type de retour dans pxTypeText, où n est un nombre compris entre 1 et 9. Cela indique à Excel de prendre la valeur de la variable à l’emplacement vers lequel pointe l’argument _n_th in_pxTypeText_as la valeur de retour. Cette opération est également appelée modification sur place. The_n_th argument doit être un type de données pass-by-reference (C, D, E, F, F%, G, K, K%, L, M, N, O, O%, P, Q, R ou U). La fonction DLL ou la ressource de code doit également être déclarée avec l’mot clé void dans les langages C/C++ (ou la procédure mot clé dans le langage Pascal).
Par exemple, une fonction DLL qui accepte une chaîne terminée par un caractère Null et deux pointeurs vers des entiers en tant qu’arguments peut modifier la chaîne sur place. Utilisez « 1FMM » comme argument pxTypeText et déclarez la fonction comme void.
Les versions précédentes d’Excel utilisées > au début de pxTypeText pour indiquer que la fonction a été déclarée comme void et que le premier argument devait être modifié sur place. Il n’y avait aucun moyen de modifier un autre argument que le premier. équivaut > à n = 1 dans les versions actuelles d’Excel et cette utilisation de > dans les fonctions synchrones est prise en charge uniquement pour la compatibilité descendante.
Fonctions asynchrones
Une fonction asynchrone, indiquée à l’aide d’un paramètre de type X dans pxTypeText, ne retourne pas son résultat à partir de l’appel de fonction initial. Au lieu de cela, vous devez déclarer une fonction asynchrone comme void et ultérieurement le complément retourne le résultat par le biais d’un rappel. La fonction asynchrone doit être inscrite à l’aide > de au début de pxTypeText. Dans les fonctions asynchrones, > indique que la fonction est déclarée comme void, mais n’indique pas que le premier argument est modifié sur place. Pour plus d’informations sur les fonctions asynchrones, consultez Fonctions User-Defined asynchrones.
Inscription des fonctions de feuille de calcul en tant qu’équivalents de feuille de macro (gestion des cellules non calculées)
Le fait de placer un # caractère après le dernier code de paramètre dans pxTypeText donne à la fonction les mêmes autorisations d’appel que les fonctions sur une feuille de macro. Elle comprennent notamment :
La fonction peut récupérer les valeurs des cellules qui n’ont pas encore été calculées dans ce cycle de recalcul.
La fonction peut appeler n’importe quelle fonction d’informations XLM (classe 2), par exemple xlfGetCell.
Si le signe numérique (#) n’est pas présent : l’évaluation d’une cellule non calculée entraîne une erreur xlretUncalced , et la fonction actuelle est appelée à nouveau une fois que la cellule a été calculée ; L’appel d’une fonction d’informations XLM autre que xlfCaller génère une erreur xlretInvXlfn .
Inscription des fonctions de feuille de calcul comme thread-safe
À compter d’Excel 2007, Excel peut effectuer un recalcul de classeur multithread. Cela signifie qu’il peut affecter différentes instances d’une fonction thread-safe à des threads simultanés pour la réévaluation. À compter d’Excel 2007, la plupart des fonctions de feuille de calcul intégrées sont thread-safe. À compter d’Excel 2007, Excel permet également aux XLL d’inscrire des fonctions de feuille de calcul en tant que thread-safe. Pour ce faire, incluez un $ caractère après le dernier code de paramètre dans pxTypeText.
Remarque
Seules les fonctions de feuille de calcul peuvent être déclarées comme thread-safe. Excel ne considère pas qu’une fonction d’équivalent de feuille de macro est thread-safe, de sorte que vous ne pouvez pas ajouter à la fois des # caractères et $ à l’argument pxTypeText .
Si vous avez inscrit une fonction comme thread-safe, vous devez vous assurer qu’elle se comporte de manière thread-safe, bien qu’Excel rejette tout appel de thread non sécurisé via l’API C. Par exemple, si une fonction thread-safe tente d’appeler xlfGetCell, l’appel échoue avec l’erreur xlretNotThreadSafe .
Inscription des fonctions de feuille de calcul comme étant sécurisées pour le cluster
À compter d’Excel 2010, Excel peut décharger les appels de fonction vers un fournisseur de cluster de calcul désigné. Pour plus d’informations, consultez Fonctions sécurisées de cluster. Toutes les fonctions de feuille de calcul XLL inscrites en tant que cluster sécurisé participent au déchargement si un cluster est disponible. Les fonctions sans risque de cluster sont inscrites en incluant le caractère & après le dernier code de paramètre dans l’argument pxTypeText .
Si vous avez inscrit une fonction en tant que cluster-safe, vous devez vous assurer qu’elle se comporte de manière sécurisée pour le cluster. Pour plus d’informations, consultez Fonctions sécurisées de cluster.
Remarque
Seules les fonctions de feuille de calcul peuvent être déclarées comme sécurisées pour le cluster. Excel ne considère pas qu’une fonction d’équivalent de feuille de macro est sécurisée pour le cluster, de sorte que vous ne pouvez pas ajouter à la fois # et & caractères à l’argument pxTypeText . Les fonctions de feuille de calcul peuvent être déclarées à la fois comme étant sécurisées pour le cluster et comme thread-safe. Dans ce cas, Excel permet à ces fonctions de prendre part au recalcul multithread lorsque le déchargement du cluster est désactivé.
Noms de catégorie
Utilisez les instructions suivantes pour déterminer la catégorie dans laquelle placer vos fonctions XLL.
- Si la fonction effectue une opération qui peut être effectuée par l’utilisateur dans le cadre de l’interface utilisateur de votre complément, vous devez placer la fonction dans la catégorie Commandes .
- Si la fonction retourne des informations sur l’état du complément ou toute autre information utile, vous devez placer la fonction dans la catégorie Informations .
- Un complément ne doit jamais ajouter de fonctions ou de commandes à la catégorie Définie par l’utilisateur . Cette catégorie est destinée à l’usage exclusif des utilisateurs finaux.
-La catégorie est spécifiée à l’aide du paramètre pxCategory sur xlfRegister. Il peut s’agir d’un nombre ou d’un texte qui correspond à l’une des catégories standard codées en dur, ou au texte d’une nouvelle catégorie spécifiée par la DLL. Si le texte donné n’existe pas déjà, Excel crée une catégorie portant ce nom.
Le tableau suivant répertorie les catégories standard visibles lorsque vous affichez la boîte de dialogue Coller la fonction à partir d’une feuille de calcul.
| Number | Texte |
|---|---|
| 1 |
Financier |
| 2 |
Date Heure |
| 3 |
Math Trigo |
| 4 |
Texte |
| 5 |
Logique |
| 6 |
Recherche Matrices |
| 7 |
Database |
| 8 |
Statistiques |
| 9 |
Information |
| 14 |
Personnalisées |
| Ingénierie (à partir d’Excel 2007) |
|
| Cube (à partir d’Excel 2007) |
En outre, ces catégories sont également visibles lorsque vous affichez la boîte de dialogue Coller la fonction à partir d’une feuille macro.
| Number | Texte |
|---|---|
| 10 |
Commandes |
| 11 |
DDE/Externe |
| 12 |
Personnalisation |
| 13 |
Contrôle de macros |
Exemple
Consultez le code de la fonction xlAutoOpen dans \SAMPLES\GENERIC\GENERIC.C.