IMAP_ListMBs

4D v20

IMAP_ListMBs


IMAP_ListMBs ( imap_ID ; refBuzon ; nomBuzon ; arraynomsbuzon ; arrayAtribbuzon ; arraySepJerarq ; buzonesInscritos ) -> resultado

Parámetro	Tipo	Descripción
imap_ID	Entero largo	Referencia de conexión IMAP
refBuzon	Texto	Cadena vacía o nombre de buzón o nivel jerárquico
nomBuzon	Texto	Cadena vacía o nombre del buzón o Jokers
arraynomsbuzon	Array cadena	Array de nombres de buzones (rutas de acceso)
arrayAtribbuzon	Array cadena	Array de atributos de buzones
arraySepJerarq	Array cadena	Array de separadores jerárquicos
buzonesInscritos	Entero	0 = Lista todos los buzones disponibles 1 = Lista únicamente los buzones inscritos
resultado	Entero	Código de error

Descripción

El comando IMAP_ListMBs devuelve la lista de buzones disponibles para el usuario conectado y la información adjunta. Si este comando falla, se inicializan los arrays especificados.

refBuzon y nomBuzon deben ser considerados conjuntamente ya que la lista de buzones resultante dependerá de la combinación de los valores de estos parámetros.

Cuando pasa 1 en el último parámetro, buzonesInscritos, la lista devuelta puede estar restringida a los buzones a los cuales el usuario está suscrito (ver IMAP_SubscribeMB).

Si la ejecución de IMAP_ListMBs toma mucho tiempo, ya sea por un gran número de buzones a examinar o por las numerosas y complejas estructuras jerárquicas, etc., puede:

utilizar comodines (ver más adelante) con IMAP_ListMBs,
pasar 1 como parámetro buzonesInscritos, para listar únicamente los buzones definidos con el comando IMAP_SubscribeMB.

imap_ID es una referencia entero largo a una conexión abierta creada con IMAP_Login.

refBuzon es un valor texto que debe ser combinado con el parámetro nomBuzon para determinar los buzones a utilizar. La referencia (refBuzon) debe utilizarse como un directorio de trabajo actual en los sistemas Unix. En otras palabras, el nombre del buzón (nomBuzon) se interpreta como un archivo ubicado en el directorio especificado por la referencia (refBuzon). las especificaciones IMAP indican que la interpretación de la referencia (refBuzon) "depende de la implementación", esto significa que no es obligatoria. Es recomendable que el usuario reciba un modo de funcionamiento que no utilice ningún argumento de referencia refBuzon. Como tal, puede interactuar con servidores más antiguos que no implementaron el uso de argumentos de referencia.

Si refBuzon es una cadena vacía, sólo el parámetro nomBuzon se utilizará para listar los buzones.

Si refBuzon contiene el nombre de un buzón o un nivel jerárquico de buzones, debe ser usado para definir el contexto en el que debe ser interpretado el parámetro nomBuzon.

Nota: recomendamos colocar un separador jerárquico en el argumento de referencia cuando se utilice. Esto garantizará la compatibilidad del comando independientemente del servidor IMAP utilizado.

El valor a pasar en el parámetro nomBuzon depende del parámetro refBuzon.

Si nomBuzon es una cadena vacía, se devuelve el separador jerárquico.

Nota: si decide implementar un sistema de conexiones múltiples con la ayuda del parámetro refBuzon, debe permitir al usuario elegir si desea o no utilizar un separador jerárquico al inicio del nombre del buzón. La gestión del separador al inicio del nombre varía de un servidor a otro, e incluso entre diferentes sistemas de correo electrónico en el mismo servidor. En algunos casos, este separador jerárquico significará "no tener en cuenta el argumento de referencia", mientras que en otros casos, los dos parámetros se concatenan y el carácter separador se ignora.

El array arrayNomBuzon recibe la lista de nombres de buzones disponibles.

El array arrayAtribBuzon recibe la lista de atributos de los buzones disponibles.

Atributos de buzones
Hay cuatro atributos disponibles:

\Noinferiors: no existen niveles jerárquicos inferiores y ni pueden crearse.
\Noselect: este nombre no puede utilizarse como un buzón seleccionable.
\Marked: el servidor ha marcado el buzón como "interesante", probablemente el buzón contiene mensajes agregados desde la última selección.
\Unmarked: el buzón no contiene ningún mensaje adicional desde la última selección.

El array arraySepJerar recibe la lista de separadores jerárquicos de los buzones disponibles.

El separador jerárquico es un carácter utilizado para delimitar los niveles jerárquicos en un nombre de buzón. Puede utilizar este carácter para crear buzones hijos y para buscar los niveles más altos o más bajos de la jerarquía de nombres. Todos los hijos de un nivel jerárquico principal utilizan el mismo carácter separador.

buzonesInscritos es un valor entero que permite indicar si quiere recuperar la lista de buzones a los cuales el usuario está suscrito. Un valor cero lista todos los buzones usuario disponibles. Un valor de 1 lista únicamente los buzones usuario suscritos. buzonesInscritos es un parámetro opcional que si no se define tiene el valor de cero por defecto.

Ejemplo 1

El siguiente ejemplo:

IMAP_ListMBs(imap_ID;"4DIC/Work/";"Test";mbNamesArray;mbAttribsArray;mbHierarArray)

...devuelve todos los buzones disponibles del buzón “4DIC/Work/Test”.
Recuerde que si el servidor IMAP no interpreta los parámetros como lo desea, no utilice el parámetro refBuzon y concatene los valores de refBuzon y nomBuzon en el parámetro nomBuzon:

IMAP_ListMBs(imap_ID;"";"4DIC/Work/Test";mbNamesArray;mbAttribsArray;mbHierarArray)

Ejemplo 2

El siguiente ejemplo:

IMAP_ListMBs(imap_ID;"";"";mbNamesArray;mbAttribsArray;mbHierarArray)

...devuelve el separador jerárquico.

Uso de comodines

Puede utilizar comodines en los parámetros refBuzon y nomBuzon con el fin de facilitar la selección del buzón. A continuación encontrará un ejemplo que utiliza los comodines más comunes, sin embargo tenga en cuenta que la interpretación de los comodines depende del servidor IMAP; por lo tanto, estos ejemplos podrían no funcionar. En este caso, verifique los comodines de su servidor IMAP.

“ * ” reemplaza todo carácter en su posición:

IMAP_ListMBs(imap_ID;"";"*";mbNamesArray;mbAttribsArray;mbHierarArray)

... devuelve todos los buzones disponibles para el usuario conectado.

IMAP_ListMBs(imap_ID;"";"Work*";mbNamesArray;mbAttribsArray;mbHierarArray)

... devuelve todos los buzones disponibles que comiencen por la raíz “Work”.

“ % ” es similar a “ * ”, pero no remplaza el separador jerárquico. Si el comodín “%” es el último carácter del parámetro nomBuzon, los niveles jerárquicos correspondientes también se devuelven. Si estos niveles jerárquicos no son buzones seleccionables, se devuelven con el atributo \Noselect (ver el párrafo “Atributos de buzones”).

IMAP_ListMBs(imap_ID"";"Work/%";mbNamesArray;mbAttribsArray;mbHierarArray)

... devuelve todos los buzones disponibles que comienzan por la raíz "Work”, más un subnivel jerárquico adicional.

El comodín “%” puede ser útil durante el análisis por nivel de la jerarquía de los buzones.
Dada la siguiente jerarquía de buzones:

INBOX
   MailboxA
      MailboxAA
      MailboxAB
   MailboxB
      MailboxBA
      MailboxBB
   MailboxC
      MailboxCA
      MailboxCB

IMAP_ListMBs(imap_ID;"";"%";mbNamesArray;mbAttribsArray;mbHierarArray)

... devuelve INBOX, MailboxA, MailboxB y MailboxC.

IMAP_ListMBs(imap_ID;"";"MailboxA%";mbNamesArray;mbAttribsArray;mbHierarArray)

... devuelve MailboxAA y MailboxAB.

Utilizando esta técnica, puede dar al usuario una cierta flexibilidad sin devolver demasiada información

IMAP_ListMBs(imap_ID;"";"*";mbNamesArray;mbAttribsArray;mbHierarArray)

Note que los servidores IMAP pueden limitar el número de niveles a analizar.

Ver también

IMAP_GetMBStatus
IMAP_SubscribeMB