Método Items.Restrict (Outlook)

  • Artigo

Aplica um filtro à coleção Items, retornando uma nova coleção que contém todos os itens do original que coincidem com o filtro.

Sintaxe

expression. Restrict( _Filter_ )

Expressão Uma expressão que retorna um objeto Items .

Parâmetros

Nome Obrigatório/Opcional Tipo de dados Descrição
Filtro Obrigatório String Uma expressão de cadeia de caracteres de filtro a ser aplicada. Para obter detalhes, consulte o método Find.

Valor de retorno

Uma coleção de itens que representa os itens da coleção Items original que corresponde ao filtro.

Comentários

Esse método é uma alternativa ao usar o método Find ou o método FindNext para iterar em itens específicos dentro de uma coleção. Os métodos Find ou FindNext são mais rapidamente do que a filtragem se houver um pequeno número de itens. O método Restrict é significativamente mais rápido, se houver um grande número de itens na coleção, especialmente se apenas alguns itens em uma coleção grande que devem ser encontrados.

Observação

[!OBSERVAçãO] Se você estiver usando campos definidos pelo usuário como parte de uma cláusula Find ou Restrict, os campos definidos pelo usuário devem existir na pasta. Caso contrário, o código gerará um erro informando que o campo é desconhecido. Você pode adicionar um campo a uma pasta exibindo o Seletor de campos e clicando em novo.

Este método não pode ser usado e causará um erro com as seguintes propriedades:

Corpo LastFirstNoSpaceCompany
Filhos LastFirstSpaceOnlyCompany
Class LastFirstNoSpaceAndSuffix
Companies MemberCount
CompanyLastFirstNoSpace NetMeetingAlias
CompanyLastFirstSpaceOnly NetMeetingAutoStart
ContactNames NetMeetingOrganizerAlias
Contatos NetMeetingServer
ConversationIndex NetMeetingType
DLName RecurrenceState
Email1EntryID ReceivedByEntryID
Email2EntryID ReceivedOnBehalfOfEntryID
Email3EntryID ReplyRecipients
EntryID ResponseState
HTMLBody Salvo
IsOnlineMeeting Sent
LastFirstAndSuffix submitted
LastFirstNoSpace VotingOptions
AutoResolvedWinner DownloadState
BodyFormat IsConflict
InternetCodePage MeetingWorkspaceURL
Permissão

Criando filtros para os métodos Localizar e Restringir

A sintaxe do filtro varia dependendo do tipo de campo sendo filtrado.

Cadeia de Caracteres (para campos Texto)

Quando a filtragem de campos de texto, você pode usar um par de aspas simples (') ou um par de aspas duplas ("), para delimitar os valores que fazem parte do filtro. Por exemplo, todas as linhas a seguir funcionam corretamente quando o campo é do tipo Cadeia de caracteres :

sFilter = "[CompanyName] = 'Microsoft'" sFilter = "[CompanyName] = ""Microsoft"""  
sFilter = "[CompanyName] = " & Chr(34) & "Microsoft" & Chr(34)

In specifying a filter in a Jet or DASL query, if you use a pair of single quotes to delimit a string that is part of the filter, and the string contains another single quote or apostrophe, then add a single quote as an escape character before the single quote or apostrophe. Use a similar approach if you use a pair of double quotes to delimit a string. If the string contains a double quote, then add a double quote as an escape character before the double quote.

Por exemplo, na cadeia de caracteres de filtro DASL que filtra para a propriedade Subject ser igual à palavra can't, toda a cadeia de caracteres de filtro é delimitada por um par de aspas duplas e a cadeia de caracteres can't inserida é delimitada por um par de aspas individuais. Há três caracteres que você precisa escapar nesta cadeia de caracteres de filtro: a cotação dupla inicial e a cotação dupla final para a referência de propriedade de http://schemas.microsoft.com/mapi/proptag/0x0037001f, e o apóstrofo na condição de valor da palavra can't. A aplicação dos caracteres de escape apropriados permite expressar a cadeia de caracteres de filtro da seguinte forma:

filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'can''t'"

Como alternativa, você pode usar a chr(34) função para representar a cotação dupla (cujo valor de caractere ASCII é 34) que é usada como um caractere de escape. A substituição chr(34) usada como caractere de escape de aspas duplas permite expressar o último exemplo desta forma:

filter = "@SQL= " & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001f" _  
    & Chr(34) & " = " & "'can''t'"

O uso de aspas simples e duplas como caracteres de escape também é obrigatório nas consultas DASL com o operador ci_startswith ou ci_phrasematch. Por exemplo, a consulta a seguir executa uma correspondência de frase para can't no assunto da mensagem:

filter = "@SQL=" & Chr(34) & "http://schemas.microsoft.com/mapi/proptag/0x0037001E" _  
    & Chr(34) & " ci_phrasematch " & "'can''t'"

Outro exemplo é uma cadeia de caracteres de filtro DASL que filtra a propriedade Subject sendo igual às palavras the right stuff, em que a palavra stuff é fechada por aspas duplas. Nesse caso, você deve usar aspas duplas como escape da seguinte forma:

filter = "@SQL=""http://schemas.microsoft.com/mapi/proptag/0x0037001f"" = 'the right ""stuff""'"

A different set of escaping rules apply to a property reference for named properties that contain the space, single quote, double quote, or percent character. For more information, see Referencing Properties by Namespace.

Data

Embora datas e horas geralmente são armazenadas com um formato Date, Find e Restrict métodos exigem que a data e hora ser convertido em uma representação de cadeia de caracteres. Para certificar-se de que a data está formatada como Microsoft Outlook espera, use a função Format. O exemplo a seguir cria um filtro para localizar todos os contatos que foram modificados após 15 de janeiro de 1999 às 15:30.

sFilter = "[LastModificationTime] > '" & Format("1/15/99 3:30pm", "ddddd h:nn AMPM") & "'"

Operadores booleanos

operadores Boolean, TRUE/ FALSE, Sim/Não, DIANTE/OFF, e assim por diante, não devem ser convertidos em uma cadeia de caracteres. Por exemplo, para determinar se o registro no diário está habilitado para contatos, você pode usar esse filtro:

sFilter = "[Journal] = True"

Observação

[!OBSERVAçãO] Se você usar aspas como delimitadores com campos Boolean, em seguida, uma cadeia de caracteres vazia localizará itens cujos campos sejam False e todas as cadeias de caracteres não-vazias localizarão os itens cujos campos sejam True.

Keywords (ou Categories)

O campo de categorias é do tipo palavras-chave, que foi projetada para armazenar vários valores. Ao acessar programaticamente, o campo categorias se comporta como um campo de texto e a cadeia de caracteres deve corresponder exatamente. Valores na cadeia de texto são separados por uma vírgula e um espaço. Geralmente, isso significa que você não pode usar os métodos Find e Restrict em um campo de palavras-chave se ele contiver mais de um valor. Por exemplo, se você tiver um contato na categoria Business e um contato nas categorias Social e corporativos, você não pode usar facilmente os métodos Find e Restrict para recuperar todos os itens que estão na categoria comercial. Em vez disso, você pode executar um loop em todos os contatos na pasta e use a função Instr para testar se a cadeia de caracteres "Business" está contida em todo o campo de palavras-chave.

Observação

[!OBSERVAçãO] Uma exceção possível seria se você limitar o campo Categories a dois ou um número baixo dos valores. Em seguida, você pode usar os métodos Find e Restrict com o operador lógico OR para recuperar todos os contatos comerciais. Por exemplo (em pseudocódigo): "Business" OU "Business, Personal" OU "Personal, Business". As cadeias de caracteres de categoria não são sensíveis a casos.

Inteiro

Você pode procurar campos inteiro com ou sem aspas como delimitadores. Os seguintes filtros localizarão contatos que foram criados usando o Outlook 2000:

sFilter = "[OutlookInternalVersion] = 92711" sFilter = "[OutlookInternalVersion] = '92711'"

Usando variáveis como parte do filtro

Como o exemplo do método Restrict ilustra, você pode usar valores de variáveis como parte do filtro. O seguinte exemplo de código do Microsoft Visual Basic Scripting Edition (VBScript) ilustra a sintaxe que utiliza variáveis como parte do filtro.

sFullName = "Dan Wilson"  
' This approach uses Chr(34) to delimit the value.  
sFilter = "[FullName] = " & Chr(34) & sFullName & Chr(34)  
' This approach uses double quotation marks to delimit the value. sFilter = "[FullName] = """ & sFullName & """"

Usando operadores lógicos como parte do filtro

Os operadores lógicos permitidos são AND, OR e não. Estas são as variações da cláusula para o método Restrict para que você pode especificar vários critérios.

OR: o código a seguir retorna todos os itens de contato que têm como categoria Comercial ou Pessoal.

sFilter = "[Categories] = 'Personal' Or [Categories] = 'Business'"

AND: o código a seguir recupera todos os contatos pessoais que trabalham na Microsoft.

sFilter = "[Categories] = 'Personal' And [CompanyName] = 'Microsoft'"

NOT: o código a seguir recupera todos os contatos pessoais que não trabalham na Microsoft.

sFilter = "[Categories] = 'Personal' And Not([CompanyName] = 'Microsoft')"

Observações adicionais

Se você está tentando usar os métodos Find ou Restrict com campos definidos pelo usuário, os campos devem ser definidos na pasta, caso contrário, ocorrerá um erro. Não é possível executar uma operação "contém". Por exemplo, você não pode usar Find ou Restrict para procurar itens que tenham uma determinada palavra no campo assunto. Em vez disso, você pode usar o método AdvancedSearch ou você pode executar um loop em todos os itens na pasta e use a função InStr para realizar uma pesquisa dentro de um campo. Use o método Restrict para pesquisar itens que começam dentro de um determinado intervalo de caracteres. Por exemplo, para procurar todos os contatos com o último nome começando com a letra M, use este filtro:

sFilter = "[LastName] > 'LZZZ' And [LastName] < 'N'"

Exemplo

Este exemplo Visual Basic for Applications (VBA) usa o método Restrict para obter todos os itens de caixa de entrada da categoria de negócios e move-los para a pasta de negócios. Para executar esse exemplo, crie ou certificar-se de que uma subpasta chamada 'Business' existe sob a caixa de entrada.

Sub MoveItems()  
    Dim myNamespace As Outlook.NameSpace  
    Dim myFolder As Outlook.Folder  
    Dim myItems As Outlook.Items  
    Dim myRestrictItems As Outlook.Items  
    Dim myItem As Outlook.MailItem  
  
    Set myNamespace = Application.GetNamespace("MAPI")  
    Set myFolder = _  
        myNamespace.GetDefaultFolder(olFolderInbox)  
    Set myItems = myFolder.Items  
    Set myRestrictItems = myItems.Restrict("[Categories] = 'Business'")  
    For i =  myRestrictItems.Count To 1 Step -1  
        myRestrictItems(i).Move myFolder.Folders("Business")  
    Next  
End Sub

Este exemplo Visual Basic for Applications usa o método Restrict para aplicar um filtro aos itens com base na propriedade LastModificationTime do item de contato.

Public Sub ContactDateCheck()  
    Dim myNamespace As Outlook.NameSpace  
    Dim myContacts As Outlook.Items  
    Dim myItems As Outlook.Items  
    Dim myItem As Object  
      
    Set myNamespace = Application.GetNamespace("MAPI")  
    Set myContacts = myNamespace.GetDefaultFolder(olFolderContacts).Items  
    Set myItems = myContacts.Restrict("[LastModificationTime] > '01/1/2003'")  
    For Each myItem In myItems  
        If (myItem.Class = olContact) Then  
            MsgBox myItem.FullName & ": " & myItem.LastModificationTime  
        End If  
    Next  
End Sub

O exemplo do Visual Basic for Applications a seguir é o mesmo do exemplo acima, exceto que ele demostra o uso de uma variável no filtro.

Public Sub ContactDateCheck2()  
    Dim myNamespace As Outlook.NameSpace  
    Dim myContacts As Outlook.Items  
    Dim myItem As Object  
    Dim DateStart As Date  
    Dim DateToCheck As String  
    Dim myRestrictItems As Outlook.Items  
  
    Set myNameSpace = Application.GetNamespace("MAPI")  
    Set myContacts = myNameSpace.GetDefaultFolder(olFolderContacts).Items  
    DateStart = #01/1/2003#  
    DateToCheck = "[LastModificationTime] >= """ & DateStart & """"  
    Set myRestrictItems = myContacts.Restrict(DateToCheck)  
    For Each myItem In myRestrictItems  
        If (myItem.Class = olContact) Then  
            MsgBox myItem.FullName & ": " & myItem.LastModificationTime  
        End If  
    Next  
End Sub

Confira também

Objeto Items

Suporte e comentários

Tem dúvidas ou quer enviar comentários sobre o VBA para Office ou sobre esta documentação? Confira Suporte e comentários sobre o VBA para Office a fim de obter orientação sobre as maneiras pelas quais você pode receber suporte e fornecer comentários.