IMAPITable::SetColumns
Hace referencia a: Outlook 2013 | Outlook 2016
Define las propiedades concretas y el orden de las propiedades que aparecerán como columnas en la tabla.
HRESULT SetColumns(
LPSPropTagArray lpPropTagArray,
ULONG ulFlags
);
Parameters
lpPropTagArray
[in] Puntero a una matriz de etiquetas de propiedad que identifican las propiedades que se van a incluir como columnas en la tabla. La parte del tipo de propiedad de cada etiqueta se puede establecer en un tipo válido o en PR_NULL para reservar espacio para adiciones posteriores. El parámetro lpPropTagArray no se puede establecer en NULL; cada tabla debe tener al menos una columna.
ulFlags
[in] Máscara de bits de marcas que controla la devolución de una llamada asincrónica a SetColumns, por ejemplo, cuando se usa SetColumns en la notificación. Se pueden establecer las siguientes marcas:
TBL_ASYNC
Solicita que la operación de configuración de columna se realice de forma asincrónica, lo que hace que SetColumns pueda devolverse antes de que la operación se haya completado por completo.
TBL_BATCH
Permite que la tabla posponga la operación de configuración de columna hasta que se necesiten realmente los datos.
Valor devuelto
S_OK
La operación de configuración de columna se realizó correctamente.
MAPI_E_BUSY
Hay otra operación en curso que impide que se inicie la operación de configuración de columna. Se debe permitir que se complete la operación en curso o se debe detener.
Comentarios
El conjunto de columnas de una tabla es el grupo de propiedades que componen las columnas de las filas de la tabla. Hay un conjunto de columnas predeterminado para cada tipo de tabla. El conjunto de columnas predeterminado se compone de las propiedades que el implementador de tabla incluye automáticamente. Los usuarios de tabla pueden modificar este conjunto predeterminado llamando al método IMAPITable::SetColumns . Pueden solicitar que se agreguen otras columnas al conjunto predeterminado si el implementador de tablas admite que se quiten las columnas o que se cambie el orden de las columnas. SetColumns especifica las columnas que se devuelven con cada fila y el orden de estas columnas dentro de la fila.
La operación SetColumns se realiza correctamente solo después de realizar una llamada posterior para recuperar los datos de la tabla. Es entonces cuando se notifican los errores.
Notas a los implementadores
Algunos proveedores permiten una llamada a SetColumns para ordenar solo las columnas de tabla que forman parte de las columnas disponibles para una vista de tabla. Otros proveedores permiten una llamada a SetColumns para ordenar todas las columnas de tabla, incluidas las que contienen propiedades que no están en el conjunto de columnas original.
Cuando se establece TBL_BATCH para operaciones asincrónicas, los proveedores deben devolver un tipo de propiedad de PT_ERROR y un valor de propiedad NULL para las columnas que no se admiten.
No es necesario responder a la marca de TBL_ASYNC que solicita que la operación sea asincrónica. Si no admite la definición asincrónica del conjunto de columnas, realice la operación de forma sincrónica. Si puede admitir la marca de TBL_ASYNC y otra operación asincrónica todavía está en curso, devuelva MAPI_E_BUSY. De lo contrario, devuelva S_OK independientemente de si admite o no todas las propiedades incluidas en la matriz de etiquetas de propiedad. Los errores resultantes de propiedades no admitidas deben devolverse de métodos IMAPITable que recuperen datos, como QueryRows.
No genere notificaciones para las filas de tabla que están ocultas de la vista mediante llamadas a Restrict.
Al enviar notificaciones de tabla, el orden de las propiedades del miembro de fila de la estructura TABLE_NOTIFICATION y el orden especificado por la llamada a SetColumns más reciente deben ser los mismos que en el momento en que se envió la solicitud de notificación.
Otra marca, TBL_BATCH, permite a los autores de llamadas especificar que el implementador de tabla puede aplazar la evaluación de los resultados de la operación hasta un momento posterior. Siempre que sea posible, los autores de llamadas deben establecer esta marca porque la operación por lotes mejora el rendimiento.
A menudo resulta conveniente que los autores de llamadas reserven algunas columnas en el conjunto de filas recuperado para que los valores se agreguen más adelante. Para ello, los autores de la llamada colocan PR_NULL (PidTagNull) en las posiciones deseadas en la matriz de etiquetas de propiedad que se pasa a SetColumns; a continuación, la tabla pasará PR_NULL en esas posiciones en todas las filas recuperadas con QueryRows.
Notas para los llamadores
Al compilar la matriz de etiquetas de propiedad para el parámetro lpPropTagArray , ordene las etiquetas en el orden en que desea que las columnas aparezcan en la vista de tabla.
Puede especificar propiedades multivalor que se incluirán en el conjunto de columnas aplicando la marca de instancia multivalor, o MVI_FLAG constante, a la etiqueta de propiedad. Establezca esta marca pasando la etiqueta de propiedad de la versión de un solo valor de la propiedad como parámetro a la macro MVI_PROP como se indica a continuación:
MVI_PROP(ulPropTag)
La macro MVI_PROP establecerá MVI_FLAG para la propiedad, convirtiendo la etiqueta en una etiqueta multivalor. Si intenta llamar erróneamente a MVI_PROP en una propiedad de un solo valor, MAPI omitirá la llamada y dejará la etiqueta de propiedad sin cambios.
Puede incluir etiquetas de propiedad establecidas en PR_NULL en la matriz de etiquetas de propiedad para reservar espacio en el conjunto de columnas. Reservar espacio permite agregar a un conjunto de columnas sin tener que asignar una nueva matriz de etiquetas de propiedad.
Cuando la llamada a SetColumns provoca un cambio en el orden de las columnas de una tabla y una o varias de estas columnas representan una propiedad multivalor, es posible que aumente el número de filas de la tabla. Si esto ocurre, se descartan todos los marcadores de la tabla. Para obtener más información sobre cómo afectan las columnas multivalor a las tablas, vea Trabajar con columnas multivalor.
Establecer columnas es de forma predeterminada una operación sincrónica. Sin embargo, puede permitir que la tabla posponga la operación hasta el momento en que se necesiten los datos estableciendo la marca de TBL_BATCH. Establecer esta marca puede mejorar el rendimiento. Otra marca, TBL_ASYNC, convierte la operación en asincrónica, lo que permite que SetColumns devuelva antes de que se complete la operación. Para determinar cuándo se produce la finalización, llame a IMAPITable::GetStatus.
Si una llamada a SetColumns devuelve MAPI_E_BUSY, lo que indica que otra operación impide que se inicie la operación, puede llamar a IMAPITable::Abort para detener la operación en curso.
También puede llamar a HrAddColumnsEx para cambiar un conjunto de columnas. La diferencia entre HrAddColumnsEx e IMAPITable::SetColumns es que HrAddColumnsEx es menos flexible; solo puede agregar columnas. Las columnas adicionales se colocan al principio del conjunto de columnas; todas las columnas existentes aparecen después de estas columnas.
Referencia de MFCMAPI
Para obtener un ejemplo de código de MFCMAPI, vea la siguiente tabla.
| Archivo | Función | Comment |
|---|---|---|
| ContentsTableListCtrl.cpp |
CContentsTableListCtrl::D oSetColumns |
MFCMAPI usa el método IMAPITable::SetColumns para establecer las columnas deseadas para la tabla. |