xlfRegister (Formulario 1)
Hace referencia a: Excel 2013 | Office 2013 | Visual Studio
Se puede llamar desde un comando DLL o XLL al que ha llamado Microsoft Excel. Esto es igual a llamar a REGISTER desde una hoja de macros XLM de Excel.
xlfRegister se puede llamar de dos formas:
xlfRegister (Formulario 1): registra un único comando o función.
xlfRegister (Formulario 2): carga y activa un XLL.
Llamada en el formulario 1, esta función hace que una función o comando DLL esté disponible para Excel, establece su recuento de uso en 1 y devuelve su identificador de registro, que se puede usar para llamar a la función más adelante mediante el xlUDF o la función xlfCall . El identificador de registro también se usa para anular el registro de la función mediante xlfUnregister (Formulario 1). Si la función se ha registrado, al llamar a xlfRegister se incrementa de nuevo su número de uso.
Este formulario de la función también define un nombre oculto que es el argumento de texto de la función, pxFunctionText, y que se evalúa como el identificador de registro de la función o comando. Al anular el registro de la función, elimine este nombre mediante xlfSetName. Para obtener más información, consulta Problemas conocidos en el desarrollo de XLL de 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,
...);
Parameters
pxModuleText (xltypeStr)
Nombre del archivo DLL que contiene la función. Esto se puede obtener llamando a la función de solo XLL xlGetName si la función registrada también está dentro del archivo DLL que se está ejecutando actualmente.
pxProcedure (xltypeStr o xltypeNum)
Si es una cadena, el nombre de la función que se va a llamar tal y como aparece en el código DLL. Si es un número, el número de exportación ordinal de la función a la que se va a llamar. Para mayor claridad, use siempre el formulario de cadena.
pxTypeText (xltypeStr)
Cadena opcional que especifica los tipos de argumentos de la función y el tipo del valor devuelto de la función. Para más información, vea la sección Observaciones. Este argumento se puede omitir para un archivo DLL independiente (XLL) que incluye una función xlAutoRegister o xlAutoRegister12.
Nota:
xlAutoRegister12 solo se admite en Excel 2007.
Si se llama a xlfRegister con este argumento ausente, Excel llama a xlAutoRegister o xlAutoRegister12, si existe en el archivo DLL especificado, que debería registrar correctamente la función proporcionando esta información.
pxFunctionText (xltypeStr)
Nombre de la función tal como aparecerá en el Asistente para funciones. Este argumento es opcional; Si se omite, la función no está disponible en el Asistente para funciones y solo se puede llamar mediante la función CALL mediante el identificador de registro de funciones de una hoja de macros XLM. Por lo tanto, para el uso normal de la hoja de cálculo, debe controlar este argumento según sea necesario.
pxArgumentText (xltypeStr)
Cadena de texto opcional que describe los argumentos de la función. El usuario lo ve en el Asistente para funciones. Si se omite, Excel construye descripciones básicas de pxTypeText.
pxMacroType (xltypeNum o xltypeInt)
Argumento opcional que indica el tipo de punto de entrada XLL. El valor predeterminado, si se omite, es 1.
| valor pxMacroType |
0 |
1 |
2 |
|---|---|---|---|
| Se puede llamar desde una hoja de cálculo |
Sí |
Sí |
No |
| Se puede llamar desde una hoja de macros |
Sí |
Sí |
Sí |
| Se puede llamar a desde una definición de nombre definida |
Sí |
Sí |
Sí |
| Se puede llamar a desde una expresión de formato condicional |
Sí |
Sí |
No |
| Aparece en el Asistente para funciones para funciones de hoja de cálculo |
No |
Sí |
No |
| Aparece en el Asistente para funciones para funciones de hoja de macros |
No |
Sí |
Sí |
En la práctica, debe usar 1 para las funciones de hoja de cálculo, 1 para las funciones equivalentes de hoja de macros (registradas como tipo #) a las que desea llamar desde la hoja de cálculo y 2 para los comandos.
Nota:
Los comandos XLL están ocultos y no se muestran en los cuadros de diálogo para ejecutar macros, aunque sus nombres se pueden escribir en cualquier lugar donde se requiera un nombre de comando válido.
pxCategory (xltypeStr o xltypeNum)
Argumento opcional que permite especificar a qué categoría debe pertenecer la nueva función o comando. El Asistente para funciones divide las funciones por tipo (categoría). Puede especificar un nombre de categoría o un número secuencial, donde el número es la posición en la que aparece la categoría en el Asistente para funciones. Para obtener más información, consulte la sección "Nombres de categoría". Si se omite, se asume la categoría Definida por el usuario.
pxShortcutText (xltypeStr)
Cadena de un carácter que distingue mayúsculas de minúsculas que especifica la clave de control asignada a este comando. Por ejemplo, "A" asigna este comando a CONTROL+MAYÚS+A. Este argumento es opcional y solo se usa para comandos.
pxHelpTopic (xltypeStr)
Referencia opcional al archivo de Ayuda (.chm o .hlp) que se muestra cuando el usuario hace clic en el botón Ayuda (cuando se muestra la función personalizada). Puede estar en el formulario filepath!HelpContextID o https://address/path_to_file_in_site!0. Ambas partes antes y después del "!" son necesarias. HelpContextID no debe contener comillas simples y Excel lo convertirá en un entero sin signo de 4 bytes de largo, en formato decimal. Cuando se usa el formulario de dirección URL, Excel abre solo el archivo de ayuda al que se hace referencia.
pxFunctionHelp (xltypeStr)
Cadena opcional que describe la función personalizada cuando se selecciona en el Asistente para funciones.
pxArgumentHelp1 (xltypeStr)
Opcional. La primera de las cadenas que describen los argumentos personalizados de la función cuando la función está seleccionada en el Asistente para funciones. En Excel 2003 y versiones anteriores, xlfRegister puede tomar, como máximo, 30 argumentos para que pueda proporcionar esta ayuda solo para los primeros 20 argumentos de función. A partir de Excel 2007, xlfRegister puede tomar hasta 255 argumentos para que pueda proporcionar esta ayuda para hasta 245 parámetros de función.
Valor de la propiedad/valor devuelto
Si el registro se realizó correctamente, esta función devuelve el identificador de registro de la función (xltypeNum), que se puede usar en llamadas a xlUDF y xlfUnregister en un archivo DLL, o con CALL y UNREGISTER en una hoja de macros XLM. De lo contrario, devuelve un #VALUE! Error.
Comentarios
Tipos de datos
El argumento pxTypeText especifica el tipo de datos del valor devuelto y los tipos de datos de todos los argumentos para la función DLL o el recurso de código. El primer carácter de pxTypeText especifica el tipo de datos del valor devuelto. Los caracteres restantes indican los tipos de datos de todos los argumentos. Por ejemplo, una función DLL que devuelve un número de punto flotante y toma un entero y un número de punto flotante como argumentos requerirían "BIB" para el argumento pxTypeText .
Los tipos de datos y las estructuras utilizados por Excel para intercambiar datos con XLL se resumen en las dos tablas siguientes.
En la primera tabla se enumeran los tipos admitidos en todas las versiones de Excel.
| Tipo de datos | Paso por valor | Paso por referencia (puntero) | Comentarios |
|---|---|---|---|
| Booleano |
A |
L |
short [int] (0=false o 1=true) |
| double |
B |
E |
|
| Char* |
C, F |
Cadena de bytes en ASCII terminada en null |
|
| unsigned char * |
D, G |
Cadena de bytes ASCII contada |
|
| unsigned short [int] |
H |
WORD de 16 bits |
|
| [signed] short [int] |
I |
M |
Entero de 16 bits con signo |
| [signed long] int |
J |
N |
Entero de 32 bits con signo |
| FP |
K |
Estructura de matriz con punto flotante |
|
| Matriz |
O |
Se pasan tres argumentos: - unsigned short int * - unsigned short int * - double [] |
|
| XLOPER |
P |
Matrices y valores de la hoja de cálculo de tipo variable |
|
| Valor | R |
Referencias de rango, matrices y valores |
En Excel 2007 se introdujeron los siguientes tipos de datos para admitir las cuadrículas más grandes y las cadenas Unicode largas.
| Tipo de datos | Paso por valor | Paso por referencia (puntero) | Comentarios |
|---|---|---|---|
| unsigned short * |
C%, F% |
Cadena de caracteres anchos Unicode terminada en null |
|
| unsigned short * |
D%, G% |
Cadena de caracteres anchos Unicode contada |
|
| FP12 |
K% |
Estructura de matriz de punto flotante de cuadrícula más grande |
|
| Matriz |
O% |
Se pasan tres argumentos: - signed int * / RW * - signed int * / COL * - double [] |
|
| XLOPER12 |
Q |
Matrices y valores de la hoja de cálculo de tipo variable |
|
| Valor | U |
Referencias de rango, matrices y valores |
A partir de Excel 2010 se introdujeron los siguientes tipos de datos:
| Tipo de datos | Paso por valor | Paso por referencia (puntero) | Comentarios |
|---|---|---|---|
| XLOPER12 |
X |
El identificador asincrónico se usa para realizar un seguimiento de una llamada a función asincrónica pendiente por excel y XLL.La existencia del tipo de parámetro en la cadena de tipo también designa la función como asincrónica. Para obtener más información sobre las funciones asincrónicas, vea Funciones de User-Defined asincrónicas. |
Los tipos de cadena F, F%, G, y G% se usan para los argumentos modificados en sitio.
Al trabajar con los tipos de datos que se muestran en la tabla anterior, tenga en cuenta lo siguiente:
- Las declaraciones en lenguaje C suponen que el compilador usa dobles de 8 bytes, enteros cortos de 2 bytes y enteros largos de 4 bytes de forma predeterminada.
- Todas las funciones de archivos DLL y recursos de código se llaman mediante la convención de llamada de __stdcall .
- Cualquier función que devuelva un tipo de datos por referencia, es decir, que devuelva un puntero a algo, puede devolver de forma segura un puntero NULL. Excel interpreta un puntero nulo como un #NUM! Error.
Información adicional del tipo de datos
Esta sección contiene información detallada sobre los tipos de datos E, F, F%, G, G%, K, O, P, Q, R y U , y otra información sobre el argumento pxTypeText .
Tipo de datos E
Excel espera que un archivo DLL que usa el tipo de datos E pase punteros a números de punto flotante en la pila. Esto puede causar problemas con algunos lenguajes (por ejemplo, Borland C++) que esperan que el número se pase en la pila del emulador de coprocesador. La solución alternativa consiste en pasar un puntero al número de la pila de coprocesador. En el ejemplo siguiente se muestra cómo devolver un doble 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);
}
Tipos de datos F, F%, G y G%
Con los tipos de datos F, F%, G y G% , una función puede modificar un búfer de cadena asignado por Excel. Si el código de tipo de valor devuelto es uno de estos tipos, Excel omite el valor devuelto por la función. En su lugar, Excel busca en la lista de argumentos de función el primer tipo de datos correspondiente (F, F%, G o G%) y, a continuación, toma el contenido actual del búfer de cadena asignado como valor devuelto. Todas las versiones de Excel asignan 256 bytes para las cadenas ASCII F y G , y a partir de Excel 2007 se asignan 65 536 bytes, suficientes para 32 768 caracteres Unicode, para las cadenas Unicode F% y G% . Recuerde que los búferes deben incluir un carácter de recuento (tipos G y G%) o un carácter de terminación nula (tipos F y F%), de modo que las longitudes máximas reales de cadena sean 255 y 32 767. Las cadenas Unicode y, por lo tanto, los argumentos F% y G% , solo están disponibles a través de la API de C en Excel.
Tipos de datos K y K%
Los tipos de datos K y K% usan punteros a las estructuras FP de tamaño variable y FP12, respectivamente. Estas estructuras se definen en XLLCALL.H. Las estructuras FP12 y, por lo tanto, los argumentos de tipo K% , solo se admiten a partir de Excel 2007.
Tipos de datos O y O%
Los tipos de datos O y O% solo se pueden usar para argumentos, no valores devueltos, aunque los valores se pueden devolver modificando un argumento de tipo O o O% en su lugar. Cada uno pasa tres elementos: un puntero al número de filas de una matriz, un puntero al número de columnas de una matriz y un puntero a una matriz bidimensional de números de punto flotante.
Para modificar una matriz pasada por el tipo de datos O o O% en su lugar, puede usar ">O" o ">O%" como argumento pxTypeText . Para obtener más información sobre cómo modificar una matriz, vea la sección "Modificación en contexto: funciones declaradas como nulas" en este tema.
El tipo de datos O se creó para la compatibilidad directa con archivos DLL de Fortran, que pasan argumentos por referencia.
Se admite el porcentaje de O a partir de Excel 2007 y se adapta al mayor número de filas que admite Excel.
Tipos de datos P y Q
Cuando los argumentos de función DLL se registran como XLOPER de tipo P o tipo Q XLOPER12s, Excel convierte las referencias de celda única en valores simples y referencias de varias celdas a matrices al preparar estos argumentos. En otras palabras, los tipos P y Q siempre llegarán a la función como uno de estos tipos: xltypeNum, xltypeStr, xltypeBool, xltypeErr, xltypeMulti, xltypeMissing o xltypeNil, pero no xltypeRef o xltypeSRef porque siempre se desreferencian. XLOPER12y, por lo tanto, escriba argumentos Q , solo se admiten a partir de Excel 2007.
Si los tipos xltypeMissing o xltypeNil se usan para los valores devueltos, Excel los interpreta como cero numérico. xltypeMissing se pasa cuando el autor de la llamada omite un argumento. xltypeNil se pasa cuando el autor de la llamada pasa una referencia a una celda vacía. Cuando un rango de celdas se convierte en un xltypeMulti para pasarse como tipo P o Q, las celdas en blanco dentro del rango se convierten en elementos de matriz xltypeNil . Los elementos que faltan en una matriz literal se pasan de forma similar como elementos xltypeNil .
Funciones volátiles y actualización
En una hoja de cálculo, puede hacer que una función DLL o un recurso de código sean volátiles, de modo que se vuelva a calcular cada vez que se vuelva a calcular la hoja de cálculo. Para ello, agregue un signo de exclamación (!) después del último código de argumento en el argumento pxTypeText .
Nota:
De forma predeterminada, las funciones que toman el tipo R XLOPER o el tipo U XLOPER12s y que se registran como equivalentes de hoja de macros (tipo #; vea la sección siguiente) se controlan como volátiles en Excel.
Funciones declaradas como nulas
Hay dos casos que llaman a declarar una función como nula. En ambos casos, la función devuelve su resultado por otros medios.
Modificación en su lugar
Puede usar un solo dígito n para el código de tipo devuelto en pxTypeText, donde n es un número de 1 a 9. Esto indica a Excel que tome el valor de la variable en la ubicación a la que apunta el argumento _n_th in_pxTypeText_as el valor devuelto. Esto también se conoce como modificación en contexto. The_n_th argumento debe ser un tipo de datos de paso a referencia (C, D, E, F, F%, G, G%, K, K%, L, M, N, O, O%, P, Q, R o U). La función DLL o el recurso de código también se deben declarar con la palabra clave void en los lenguajes C/C++ (o la palabra clave procedure en el lenguaje Pascal).
Por ejemplo, una función DLL que toma una cadena terminada en NULL y dos punteros a enteros como argumentos puede modificar la cadena en su lugar. Use "1FMM" como argumento pxTypeText y declare la función como void.
Las versiones anteriores de Excel se usaban > al principio de pxTypeText para indicar que la función se declaró como void y que el primer argumento se modificaría en su lugar; no había ninguna manera de modificar ningún argumento que no fuera el primero. > es equivalente a n = 1 en las versiones actuales de Excel y este uso de > en funciones sincrónicas solo se admite para la compatibilidad con versiones anteriores.
Funciones asincrónicas
Una función asincrónica, que se indica mediante un parámetro de tipo X en pxTypeText, no devuelve su resultado de la llamada de función inicial. En su lugar, debe declarar una función asincrónica como void y, posteriormente, el complemento devuelve el resultado a través de una devolución de llamada. La función asincrónica debe registrarse mediante > al principio de pxTypeText. En las funciones asincrónicas, > denota que la función se declara como nula, pero no indica que el primer argumento se modifique en su lugar. Para obtener más información sobre las funciones asincrónicas, vea Funciones de User-Defined asincrónicas.
Registro de funciones de hoja de cálculo como equivalentes de hoja de macros (control de celdas no calculadas)
La colocación de un # carácter después del último código de parámetro en pxTypeText proporciona a la función los mismos permisos de llamada que las funciones de una hoja de macros. Son las siguientes:
La función puede recuperar los valores de las celdas que aún no se han calculado en este ciclo de actualización.
La función puede llamar a cualquiera de las funciones de información XLM (clase 2), por ejemplo, xlfGetCell.
Si el signo de número (#) no está presente: la evaluación de una celda sin calcular da como resultado un error xlretUncalced y se vuelve a llamar a la función actual una vez calculada la celda; Llamar a cualquier función de información XLM que no sea xlfCaller da como resultado un error xlretInvXlfn .
Registro de funciones de hoja de cálculo como seguras para subprocesos
A partir de Excel 2007, Excel puede realizar una actualización multiproceso del libro. Esto significa que puede asignar diferentes instancias de una función segura para subprocesos a subprocesos simultáneos para su reevaluación. A partir de Excel 2007, la mayoría de las funciones de hoja de cálculo integradas son seguras para subprocesos. A partir de Excel 2007, Excel también permite que las XLL registren funciones de hoja de cálculo como seguras para subprocesos. Para ello, incluya un $ carácter después del último código de parámetro en pxTypeText.
Nota:
Solo las funciones de hoja de cálculo se pueden declarar como seguras para subprocesos. Excel no considera que una función equivalente de hoja de macros sea segura para subprocesos, por lo que no puede anexar tanto como #$ caracteres al argumento pxTypeText .
Si ha registrado una función como segura para subprocesos, debe asegurarse de que se comporta de forma segura para subprocesos, aunque Excel rechaza cualquier llamada no segura para subprocesos a través de la API de C. Por ejemplo, si una función segura para subprocesos intenta llamar a xlfGetCell, se produce un error en la llamada con el error xlretNotThreadSafe .
Registro de funciones de hoja de cálculo como seguras para clústeres
A partir de Excel 2010, Excel puede descargar llamadas de función a un proveedor de clústeres de proceso designado. Para obtener más información, consulte Funciones seguras de clúster. Las funciones de hoja de cálculo XLL registradas como seguras para clústeres participan en la descarga si hay un clúster disponible. Las funciones seguras para clústeres se registran mediante la inclusión del carácter & después del último código de parámetro en el argumento pxTypeText .
Si ha registrado una función como segura para clústeres, debe asegurarse de que se comporta de forma segura para el clúster. Para obtener más información, consulte Funciones seguras de clúster.
Nota:
Solo las funciones de hoja de cálculo se pueden declarar como seguras para clústeres. Excel no considera que una función equivalente de hoja de macros sea segura para el clúster, por lo que no puede anexar ambos # caracteres y& al argumento pxTypeText . Las funciones de hoja de cálculo se pueden declarar como seguras para clústeres y seguras para subprocesos. En este caso, Excel permitirá que estas funciones participen en la actualización multiproceso cuando la descarga del clúster esté deshabilitada.
Nombres de categoría
Use las siguientes directrices para determinar en qué categoría colocar las funciones XLL.
- Si la función hace algo que el usuario podría hacer como parte de la interfaz de usuario del complemento, debe colocar la función en la categoría Comandos .
- Si la función devuelve información sobre el estado del complemento o cualquier otra información útil, debe colocar la función en la categoría Información .
- Un complemento nunca debe agregar funciones o comandos a la categoría Definida por el usuario . Esta categoría es para el uso exclusivo de los usuarios finales.
-La categoría se especifica mediante el parámetro pxCategory en xlfRegister. Puede ser un número o texto que corresponde a una de las categorías estándar codificadas de forma rígida o al texto de una nueva categoría especificada por el archivo DLL. Si el texto proporcionado aún no existe, Excel crea una nueva categoría con ese nombre.
En la tabla siguiente se enumeran las categorías estándar que son visibles cuando se ve el cuadro de diálogo Pegar función desde dentro de una hoja de cálculo.
| Number | Text |
|---|---|
| 1 |
Financiera |
| 2 |
Fecha y hora |
| 3 |
Matemáticas y trigonométricas |
| 4 |
Texto |
| 5 |
Lógicas |
| 6 |
Búsqueda y referencia |
| 7 |
Base de datos |
| 8 |
Estadísticas |
| 9 |
Information |
| 14 |
Definidas por el usuario |
| Ingeniería (a partir de Excel 2007) |
|
| Cubo (a partir de Excel 2007) |
Además, estas categorías también son visibles cuando se ve el cuadro de diálogo Pegar función desde dentro de una hoja de macros.
| Number | Text |
|---|---|
| 10 |
Comandos |
| 11 |
DDE/Externas |
| 12 |
Personalización |
| 13 |
Control de macros |
Ejemplo
Vea el código de la función xlAutoOpen en \SAMPLES\GENERIC\GENERIC.C.