IMAPIProp::SetProps
Aplica-se a: Outlook 2013 | Outlook 2016
Atualizações uma ou mais propriedades.
HRESULT SetProps(
ULONG cValues,
LPSPropValue lpPropArray,
LPSPropProblemArray FAR * lppProblems
);
Parâmetros
cValues
[in] A contagem de valores de propriedade apontados pelo parâmetro lpPropArray . O parâmetro cValues não deve ser 0.
lpPropArray
[in] Um ponteiro para uma matriz de estruturas SPropValue que contêm valores de propriedade a serem atualizados.
lppProblems
[in, out] Na entrada, um ponteiro para um ponteiro para uma estrutura SPropProblemArray ; caso contrário, NULL, indicando que não há necessidade de informações de erro. Se lppProblems for um ponteiro válido na entrada, SetProps retornará informações detalhadas sobre erros na atualização de uma ou mais propriedades.
Valor de retorno
S_OK
As propriedades foram atualizadas com êxito.
Os valores a seguir podem ser retornados na estrutura SPropProblemArray , mas não como valores retornados para SetProps:
MAPI_E_BAD_CHARWIDTH
O sinalizador MAPI_UNICODE foi definido e a implementação não dá suporte ao Unicode ou MAPI_UNICODE não foi definido e a implementação dá suporte apenas ao Unicode.
MAPI_E_COMPUTED
A propriedade não pode ser atualizada porque é somente leitura, calculada pelo provedor de serviços responsável pelo objeto.
MAPI_E_INVALID_TYPE
O tipo de propriedade é inválido.
MAPI_E_NO_ACCESS
Foi feita uma tentativa de modificar um objeto somente leitura ou acessar um objeto para o qual o usuário tem permissões insuficientes.
MAPI_E_NOT_ENOUGH_MEMORY
A propriedade não pode ser atualizada porque é maior que o tamanho do buffer de chamada de procedimento remoto (RPC).
MAPI_E_UNEXPECTED_TYPE
O tipo de propriedade não é o tipo esperado pela implementação de chamada.
Observações para implementadores
Ignore a marca de propriedade PR_NULL (PidTagNull) e todas as propriedades com um tipo de PT_ERROR. Não faça alterações nem reporte problemas na estrutura SPropProblemArray .
Retorne MAPI_E_INVALID_PARAMETER se uma propriedade do tipo PT_OBJECT estiver incluída na matriz de valor da propriedade. Também retorne esse erro se uma propriedade de vários valores for incluída na matriz e seu membro cValues estiver definido como 0.
Se a chamada tiver êxito geral, mas houver problemas com a configuração de algumas das propriedades, retorne S_OK e coloque informações sobre os problemas na entrada apropriada da estrutura SPropProblemArray à qual o parâmetro lppProblems aponta.
Notas para chamadores
Dependendo do provedor de serviços, você também pode ser capaz de alterar o tipo de propriedade passando uma marca de propriedade que contém um tipo diferente do usado anteriormente com um determinado identificador de propriedade.
Se você incluir uma marca de propriedade para uma propriedade sem suporte pelo objeto e a implementação de SetProps permitir a criação de novas propriedades, a propriedade será adicionada ao objeto. Qualquer valor anterior armazenado com o identificador de propriedade usado para a nova propriedade é descartado.
Observe que o S_OK valor retornado não garante que todas as propriedades foram atualizadas com êxito. Alguns provedores armazenam em cache chamadas SetProps até receberem uma chamada que requer intervenção do provedor, como IMAPIProp::SaveChanges ou IMAPIProp::GetProps. Portanto, é possível receber valores de erro relacionados à chamada SetProps com as chamadas posteriores.
Se SetProps retornar S_OK, marcar a estrutura SPropProblemArray apontada por lppProblems para problemas de atualização de propriedades individuais. Se SetProps retornar um erro, não marcar a matriz de problemas de propriedade. Em vez disso, chame o método IMAPIProp::GetLastError do objeto.
Ao atualizar propriedades grandes, o SetProps pode falhar e retornar MAPI_E_NOT_ENOUGH_MEMORY. Não há tamanho máximo para propriedades e objetos diferentes podem ter limites diferentes. Se você lidar com propriedades potencialmente grandes, esteja preparado para chamar o método IMAPIProp::OpenProperty com IID_IStream como o identificador de interface se SetProps retornar esse valor de erro.
Chame a função MAPIFreeBuffer para liberar a estrutura SPropProblemArray .
Referência do MFCMAPI
Para ver códigos de exemplo do MFCMAPI, confira a tabela a seguir.
| Arquivo | Função | Comentário |
|---|---|---|
| PropertyEditor.cpp |
CPropertyEditor::WriteSPropValueToObject |
O MFCMAPI usa o método IMAPIProp::SetProps para gravar uma propriedade de volta em um objeto após a edição da propriedade. |