_Items.Restrict(String) Método

public:
 Microsoft::Office::Interop::Outlook::Items ^ Restrict(System::String ^ Filter);

public Microsoft.Office.Interop.Outlook.Items Restrict (string Filter);

Public Function Restrict (Filter As String) As Items

Parâmetros

Retornos

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 uso do Find(String) método ou FindNext() método 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: se você estiver usando campos definidos pelo usuário como parte de uma cláusula Localizar ou Restringir , 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:

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)

Ao pesquisar campos de texto, você pode usar um apóstrofo (') ou 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 String (cadeia de caracteres em C#):

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 a propriedade Subject sendo igual à palavra não pode, toda a cadeia de caracteres de filtro é delimitada por um par de aspas duplas e a cadeia de caracteres inserida não pode ser delimitada por um par de aspas únicas. 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 não pode. 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 função chr(34) para representar aspas duplas (cujo valor de caractere ASCII é 34), que é usada como 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 para a propriedade Subject sendo igual às palavras o material certo, em que o material da palavra é fechado 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 as datas e horas sejam normalmente armazenadas em formato de data, os métodos Find e Restrict exigem que a data e a hora sejam convertidas 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("15/15/99 15:30pm", "ddddd h:nn AMPM") & "'"

Operadores booleanos

Os operadores Boolean, TRUE/FALSE, YES/NO, ON/OFF e outros, não devem ser convertidos em uma sequência de caracteres. Por exemplo, para determinar se o diário está habilitado para contatos, você pode usar este filtro:

sFilter = "[Diário] = True"

Observação: se você usar aspas como delimitadores com campos boolianos , uma cadeia de caracteres vazia encontrará itens cujos campos são False e todas as cadeias de caracteres não vazias encontrarão itens cujos campos são 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: uma possível exceção é se você limitar o campo Categorias a dois ou um número baixo de 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 (no pseudocódigo): "Business" ou "Comercial, pessoal" ou "Pessoal, Business". Cadeias de caracteres de categoria não diferenciam maiúsculas de minúsculas.

Número inteiro

Você pode procurar campos inteiro com ou sem aspas como delimitadores. Os seguintes filtros encontrarão contatos 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 exemplo de código do Microsoft Visual Basic a seguir ilustra a sintaxe que usa variáveis como parte do filtro.

sFullName = "Dan Wilson"

' Essa abordagem usa Chr(34) para delimitar o valor.

sFilter = "[FullName] = " & Chr(34) & sFullName & Chr(34)

' Essa abordagem usa aspas duplas para delimitar o valor.

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 AdvancedSearch(String, Object, Object, Object) método ou pode fazer loop em todos os itens da pasta e usar a função InStr para executar uma pesquisa em um campo. Você pode usar o método Restrict para pesquisar itens que começam em 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' e [LastName] < 'N'"

Aplica-se a