IMAP_ListMBs

4D v19

IMAP_ListMBs


IMAP_ListMBs ( imap_ID ; refCaixaCorreio ; nomCaixaCorreio ; arrayNomsCaixCor ; arrayAtribCaixCor ; arraySepHierarq ; caixCorInscritos ) -> Resultado

Parâmetro	Tipo	Descrição
imap_ID	Inteiro longo	Referencia de conexão IMAP
refCaixaCorreio	Texto	Cadeia vazia ou nome de caixa de correio ou nível hierárquico
nomCaixaCorreio	Texto	Cadeia vazia ou nome de caixa de correio ou Curinga
arrayNomsCaixCor	Array string	Array de nomes de caixas de correio (vias de acesso)
arrayAtribCaixCor	Array string	Array de atributos de caixa de correio
arraySepHierarq	Array string	Array de separadores hierárquicos
caixCorInscritos	Inteiro	0 = Lista todas as caixas de correio disponíveis 1 = Lista unicamente as caixas de correio inscritas
Resultado	Inteiro	Código de erro

Descrição

O comando IMAP_ListMBs devolve a lista de caixas de correios disponíveis para o usuário conectado e a informação adjunta. Se este comando falha, se inicializam os arrays especificados.

refCaixaCorreio e nomCaixaCorreio devem ser considerados conjuntamente já que a lista de caixas de correio resultante dependerá da combinação dos valores destes parâmetros.

Quando passa 1 no último parâmetro, caixCorInscritos, a lista devolvida pode estar restringido às caixas de correio aos quais o usuário está subscrito (ver IMAP_SubscribeMB).

Se a execução de IMAP_ListMBs toma muito tempo, seja por um grande número de caixas de correio a examinar ou pelas numerosas e complexas estruturas hierárquicas, etc., pode:

utilizar curingas (ver mais a frente) com IMAP_ListMBs,
passar 1 como parâmetro caixCorInscritos, para listar unicamente as caixas de correio definidas com o comando IMAP_SubscribeMB.

imap_ID é uma referencia inteiro longo a uma conexão aberta criada com IMAP_Login.

refCaixaCorreio é um valor texto que deve ser combinado com o parâmetro nomCaixaCorreio para determinar as caixas de correio a utilizar. A referencia (refCaixaCorreio) deve ser utilizada como um diretório de trabalho atual nos sistemas Unix. Em outras palavras, o nome da caixa de correio (nomCaixaCorreio) se interpreta como um arquivo localizado no diretório especificado pela referencia (refCaixaCorreio). as especificações IMAP indicam que a interpretação da referencia (refCaixaCorreio) "depende da implementação", isto significa que não é obrigatória. É recomendável que o usuário receba um modo de funcionamento que não utilize nenhum argumento de referencia refCaixaCorreio. Como tal, pode interagir com servidores mais antigos que não implementaram o uso de argumentos de referencia.

Se refCaixaCorreio é uma cadeia vazia, só o parâmetro nomCaixaCorreio será utilizado para listar as caixas de correio.

Se refCaixaCorreio contém o nome de uma caixa de correio ou um nível hierárquico, deve ser usado para definir o contexto no qual deve ser interpretado o parâmetro nomCaixaCorreio.

Nota: Recomendamos colocar um separador hierárquico no argumento de referencia quando se utilize. Isso vai garantir a compatibilidade do comando independentemente do servidor IMAP utilizado.

O valor a passar no parâmetro nomCaixaCorreio depende do parâmetro refCaixaCorreio.

Se nomCaixaCorreio é uma cadeia vazia, é devolvido o separador hierárquico.

Nota: Caso decida implementar um sistema de conexões múltiplas com a ajuda do parâmetro refCaixaCorreio, deve permitir ao usuário eleger se deseja ou não utilizar um separador hierárquico ao inicio do nome da caixa de correio. A gestão do separador ao inicio do nome varia de um servidor a outro, e inclusive entre diferentes sistemas de e-mail no mesmo servidor. Em alguns casos, este separador hierárquico significará "não levar em consideração o argumento de referencia", enquanto em outros casos, os dois parâmetros se concatenam e o caractere separador é ignorado.

O array arrayNomCaixCor recebe a lista de nomes de caixas de correio disponíveis.

O array arrayAtribCaixCor recebe a lista de atributos das caixas de correio disponíveis.

Atributos de caixas de correio
Há quatro atributos disponíveis:

\Noinferiors: não existem níveis hierárquicos inferiores e nem podem ser criados.
\Noselect: este nome não pode ser utilizado como uma caixa de correio selecionável.
\Marked: o servidor marcou a caixa de correio como "interessante", provavelmente a caixa de correio contém mensagens agregadas desde a última seleção.
\Unmarked: a caixa de correio não contém nenhuma mensagem adicional desde a última seleção.

O array arraySepHierarq recebe a lista de separadores hierárquicos das caixas de correio disponíveis.

O separador hierárquico é um caractere utilizado para delimitar os níveis hierárquicos em um nome de caixa de correio. Pode utilizar este caracter para criar caixas de correio filhos e para buscar os níveis mais altos ou mais baixos da hierarquia de nomes. Todos os filhos de um nível hierárquico principal utilizam o mesmo caracter separador.

caixCorInscritos é um valor inteiro que permite indicar se deseja recuperar a lista de caixas de correio aos quais o usuário está subscrito. Um valor zero lista todos as caixas de correio usuário disponíveis. Um valor de 1 lista unicamente as caixas usuário subscritos. caixCorInscritos é um parâmetro opcional que se não é definido tem como valor de zero por padrão.

Exemplo 1

O seguinte exemplo:

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

...devolve todas as caixas de correio disponíveis de “4DIC/Work/Test”.
Lembre que caso o servidor IMAP não interpreta os parâmetros como deseja, não utilize o parâmetro refCaixaCorreio e concatene os valores de refCaixaCorreio e nomCaixaCorreio no parâmetro nomCaixaCorreio:

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

Exemplo 2

O seguinte exemplo:

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

...devolve o separador hierárquico.

Uso de caracteres curinga

Pode utilizar curingas nos parâmetros refCaixaCorreio e nomCaixaCorreio com o propósito de facilitar a seleção da caixa de correio. A continuação encontrará um exemplo que utiliza os curingas mais comuns, no entanto leve em consideração que a interpretação dos curingas depende do servidor IMAP; portanto, estes exemplos poderiam não funcionar. Neste caso, verifique os curingas de seu servidor IMAP.

“ * ” substitui todo caracter em sua posição:

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

... devolve todos as caixas de correio disponíveis para o usuário conectado.

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

... devolve todos as caixas de correio disponíveis que comecem pela raiz “Work”.

“ % ” é similar a “ * ”, mas não substitui o separador hierárquico. Se o curinga “%” é o último caracter do parâmetro nomCaixaCorreio, os níveis hierárquicos correspondentes também são devolvidos. Se estes níveis hierárquicos não são caixas de correio selecionáveis, são devolvidos com o atributo \Noselect (ver o parágrafo “Atributos de caixas de correio”).

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

... devolve todos as caixas de correio disponíveis que começam pela raiz "Work”, mais um sub nível hierárquico adicional.

O curinga “%” pode ser útil durante a análises por nível da hierarquia das caixas de correio.
Dada a seguinte hierarquia de caixas de correio:

INBOX
   MailboxA
      MailboxAA
      MailboxAB
   MailboxB
      MailboxBA
      MailboxBB
   MailboxC
      MailboxCA
      MailboxCB

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

... devolve INBOX, MailboxA, MailboxB e MailboxC.

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

... devolve MailboxAA e MailboxAB.

Utilizando esta técnica, pode dar ao usuário uma certa flexibilidade sem devolver muita informação

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

Note que os servidores IMAP podem limitar o número de níveis a analisar.

Ver também

IMAP_GetMBStatus
IMAP_SubscribeMB