SPropertyRestriction
構造体サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。
フィールド
| フィールド | 型 | サイズ | x64 | x86 | 説明 |
|---|---|---|---|---|---|
| relop | DWORD | 4 | +0 | +0 | 比較演算子(RELOP_LT/RELOP_EQ等)を示す値。 |
| ulPropTag | DWORD | 4 | +4 | +4 | 比較対象とするプロパティのタグ。 |
| lpProp | SPropValue* | 8/4 | +8 | +8 | 比較する値を保持するSPropValueへのポインター。 |
公式ドキュメント
適用対象: Outlook 2013 | Outlook 2016
定数とプロパティの値を照合するために使用されるプロパティ制限について説明します。
| プロパティ | 値 |
|---|---|
| ヘッダー ファイル: |
Mapidefs.h |
typedef struct _SPropertyRestriction
{
ULONG relop;
ULONG ulPropTag;
LPSPropValue lpProp;
} SPropertyRestriction;
解説(Remarks)
SPropertyRestriction 構造体には 2 つのプロパティ タグがあります。1 つは ulPropTag メンバーにあり、もう 1 つは lpProp が指す SPropValue 構造体の ulPropTag メンバーにあります。MAPI では、プロパティ識別子フィールドとプロパティ型フィールドの両方が必要です。SPropertyRestriction の ulPropTag は照合対象のプロパティであり、SPropertyRestriction の lpProp ポインターが指す SPropValue の ulPropTag の型は、lpProp 共用体のメンバーの値をどのように解釈するかを示します。2 つのプロパティ型は一致していなければなりません。一致しない場合、その制限を IMAPITable::Restrict または IMAPITable::FindRow の呼び出しで使用したときに、エラー値 MAPI_E_TOO_COMPLEX が返されます。
比較の順序は (プロパティ値) (関係演算子) (定数値) です。
プロパティ制限を IMAPITable::Restrict または IMAPITable::FindRow に渡したときに対象のプロパティが存在しない場合、その制限の結果は未定義です。プロパティ制限と EXIST 制限を結合する AND 制限を作成することで、呼び出し元は正確な結果を保証できます。EXIST 制限の定義には SExistRestriction 構造体を、AND 制限の定義には SAndRestriction 構造体を使用します。
Exchange Server 2019 に固有のケースでは、サーバー上で実行される比較は、存在しないプロパティがあたかも存在し、そのデータ型で可能な最小値よりも小さい値を持っているかのように扱われる動作を示します。つまり、たとえば PR_SENSITIVITY プロパティを持たない MAPI オブジェクトを SPropertyRestriction{RELOP_LT, PR_SENSITIVITY, {PR_SENSITIVITY, 0, {.l = INT_MIN}} 構造体でテストした場合、比較の結果は "true" になります。(これは前述の「未定義である」という仕様と矛盾しません。)
複数値プロパティ タグは、テーブルを実装するサービス プロバイダーがそれらをサポートしている場合、プロパティ制限で使用できます。サポートされている場合、複数値プロパティ タグは、単一値プロパティ タグを使用できる場所であればどこでも使用できます。
複数値プロパティ タグは、次のメソッドで使用できます。
2 つのプロパティ タグが一致しない注目すべきケースは、複数値プロパティに対して制限を行う場合です。この場合、次の条件が満たされていなければなりません。
SPropertyRestriction の ulPropTag のプロパティ型に複数値プロパティ型を示すビット フラグ MV_FLAG (0x1000) が含まれている場合、SPropValue の ulPropTag のプロパティ型は、前者から MV_FLAG ビット フラグを除いたもの、つまりその逆と一致していなければなりません。 > たとえば、カテゴリのような複数値のカスタム文字列プロパティを、プロパティ 0x8012101f のプロパティ タグ (つまり PROP_TAG(MV_FLAG|PT_UNICODE, 0x8012)) を使用して制限する場合、対応する SPropertyRestriction は次のようになります。
SPropertyRestriction.ulPropTag = 0x8012101f; // attempt to restrict a MultiValue property
SPropertyRestriction.lpProp->ulPropTag = 0x8012001f; // the lpszW member of the Value property is valid> SPropertyRestriction.lpProp.Value->lpszW = L"My Category";> SPropValue の ulPropTag のプロパティ型に MV_FLAG ビット フラグが含まれている場合は、MAPI_E_TOO_COMPLEX が返される可能性が高いことに注意してください。
SPropertyRestriction 構造体の詳細については、About Restrictions を参照してください。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp)
各言語での定義
#include <windows.h>
// SPropertyRestriction (x64 16 / x86 12 バイト)
typedef struct SPropertyRestriction {
DWORD relop;
DWORD ulPropTag;
SPropValue* lpProp;
} SPropertyRestriction;using System;
using System.Runtime.InteropServices;
[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct SPropertyRestriction
{
public uint relop;
public uint ulPropTag;
public IntPtr lpProp;
}Imports System.Runtime.InteropServices
<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure SPropertyRestriction
Public relop As UInteger
Public ulPropTag As UInteger
Public lpProp As IntPtr
End Structureimport ctypes
from ctypes import wintypes
class SPropertyRestriction(ctypes.Structure):
_fields_ = [
("relop", wintypes.DWORD),
("ulPropTag", wintypes.DWORD),
("lpProp", ctypes.c_void_p),
]#[repr(C)]
pub struct SPropertyRestriction {
pub relop: u32,
pub ulPropTag: u32,
pub lpProp: *mut core::ffi::c_void,
}import "golang.org/x/sys/windows"
type SPropertyRestriction struct {
relop uint32
ulPropTag uint32
lpProp uintptr
}type
SPropertyRestriction = record
relop: DWORD;
ulPropTag: DWORD;
lpProp: Pointer;
end;const SPropertyRestriction = extern struct {
relop: u32,
ulPropTag: u32,
lpProp: ?*anyopaque,
};type
SPropertyRestriction {.bycopy.} = object
relop: uint32
ulPropTag: uint32
lpProp: pointerstruct SPropertyRestriction
{
uint relop;
uint ulPropTag;
void* lpProp;
}HSP用 定義
HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; SPropertyRestriction サイズ: 12 バイト(x86)
dim st, 3 ; 4byte整数×3(構造体サイズ 12 / 4 切り上げ)
; relop : DWORD (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; ulPropTag : DWORD (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; lpProp : SPropValue* (+8, 4byte) varptr(st)+8 を基点に操作(4byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; SPropertyRestriction サイズ: 16 バイト(x64)
dim st, 4 ; 4byte整数×4(構造体サイズ 16 / 4 切り上げ)
; relop : DWORD (+0, 4byte) st.0 = 値 / 値 = st.0 (lpoke/lpeek も可)
; ulPropTag : DWORD (+4, 4byte) st.1 = 値 / 値 = st.1 (lpoke/lpeek も可)
; lpProp : SPropValue* (+8, 8byte) varptr(st)+8 を基点に操作(8byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global SPropertyRestriction
#field int relop
#field int ulPropTag
#field intptr lpProp
#endstruct
stdim st, SPropertyRestriction ; NSTRUCT 変数を確保
st->relop = 100
mes "relop=" + st->relop