Win32 API 日本語リファレンス
ホームSystem.AddressBook › ADRLIST

ADRLIST

構造体
サイズx64: 24 バイト / x86: 16 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールドサイズx64x86説明
cEntriesDWORD4+0+0aEntries 配列に含まれる宛先エントリの数。
aEntriesADRENTRY16/12+8+4ADRENTRY構造体の可変長配列(先頭要素)。

公式ドキュメント

適用対象: Outlook 2013 | Outlook 2016

1 つ以上の受信者に属する 0 個以上のプロパティを記述します。

説明
ヘッダー ファイル:
Mapidefs.h
関連するマクロ:
CbADRLIST, CbNewADRLIST, CbNewADRLIST
typedef struct _ADRLIST
{
  ULONG cEntries;
  ADRENTRY aEntries[MAPI_DIM];
} ADRLIST, FAR *LPADRLIST;

解説(Remarks)

ADRLIST 構造体には 1 つ以上の ADRENTRY 構造体が含まれ、それぞれが受信者のプロパティを記述します。受信者は未解決の場合があります。これは、そのプロパティ値の配列にエントリ識別子が含まれていないことを意味します。解決済みの受信者とは、PR_ENTRYID (PidTagEntryId) プロパティが含まれている受信者のことです。通常、解決済みの受信者は電子メール アドレスを表す PR_EMAIL_ADDRESS (PidTagEmailAddress) プロパティも持ちますが、電子メール アドレスは必須ではありません。ADRLIST 構造体は、たとえば送信メッセージの受信者リストを記述するために使用され、また MAPI がアドレス帳のエントリを表示するためにも使用されます。

ADRLIST 構造体は、テーブルの行を表すために使用される SRowSet 構造体に似ています。実際、これら 2 つの構造体は相互に交換して使用できるように設計されています。どちらも、プロパティのグループを記述する構造体の配列と、その配列内の値の数を含みます。ADRLIST 構造体では配列に ADRENTRY 構造体が格納されるのに対し、SRowSet 構造体では配列に SRow 構造体が格納されます。ADRENTRY 構造体と SRow 構造体はレイアウトが同一です。ADRLIST 構造体と SRowSet 構造体は同じメモリ割り当て規則に従うため、アドレス帳コンテナーのコンテンツ テーブルから取得した SRowSet 構造体は、ADRLIST 構造体にキャストしてそのまま使用できます。

次の図は、ADRLIST 構造体のレイアウトを示しています。

ADRLIST の構成要素

ADRLIST 構造体内の ADRENTRY 部分と SPropValue 部分は、他の部分とは独立して割り当ておよび解放を行う必要があります。つまり、各 SPropValue 構造体は、ADRENTRY 構造体のメモリが割り当てられた後に個別に割り当て、ADRENTRY 構造体が解放される前に解放しなければなりません。このようにメモリを独立して扱えるため、アドレス リストに対して受信者や個々の受信者プロパティを自由に追加または削除できます。

ADRLIST 構造体とそのすべての部分の割り当ておよび解放には、MAPIAllocateBuffer 関数と MAPIFreeBuffer 関数を使用しなければなりません。

受信者リストが大きすぎてメモリに収まらない場合、クライアントは IMessage::ModifyRecipients メソッドを呼び出して、リストの一部分を扱うことができます。この場合、クライアントはアドレス帳の共通ダイアログ ボックスを使用しないでください。

ADRENTRY 構造体のメモリを割り当てる方法の詳細については、「Managing Memory for ADRLIST and SRowSet Structures」を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp)

各言語での定義

#include <windows.h>

// ADRENTRY  (x64 16 / x86 12 バイト)
typedef struct ADRENTRY {
    DWORD ulReserved1;
    DWORD cValues;
    SPropValue* rgPropVals;
} ADRENTRY;

// ADRLIST  (x64 24 / x86 16 バイト)
typedef struct ADRLIST {
    DWORD cEntries;
    ADRENTRY aEntries[1];
} ADRLIST;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct ADRENTRY
{
    public uint ulReserved1;
    public uint cValues;
    public IntPtr rgPropVals;
}

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct ADRLIST
{
    public uint cEntries;
    [MarshalAs(UnmanagedType.ByValArray, SizeConst = 1)] public ADRENTRY[] aEntries;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure ADRENTRY
    Public ulReserved1 As UInteger
    Public cValues As UInteger
    Public rgPropVals As IntPtr
End Structure

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure ADRLIST
    Public cEntries As UInteger
    <MarshalAs(UnmanagedType.ByValArray, SizeConst:=1)> Public aEntries() As ADRENTRY
End Structure
import ctypes
from ctypes import wintypes

class ADRENTRY(ctypes.Structure):
    _fields_ = [
        ("ulReserved1", wintypes.DWORD),
        ("cValues", wintypes.DWORD),
        ("rgPropVals", ctypes.c_void_p),
    ]

class ADRLIST(ctypes.Structure):
    _fields_ = [
        ("cEntries", wintypes.DWORD),
        ("aEntries", ADRENTRY * 1),
    ]
#[repr(C)]
pub struct ADRENTRY {
    pub ulReserved1: u32,
    pub cValues: u32,
    pub rgPropVals: *mut core::ffi::c_void,
}

#[repr(C)]
pub struct ADRLIST {
    pub cEntries: u32,
    pub aEntries: [ADRENTRY; 1],
}
import "golang.org/x/sys/windows"

type ADRENTRY struct {
	ulReserved1 uint32
	cValues uint32
	rgPropVals uintptr
}

type ADRLIST struct {
	cEntries uint32
	aEntries [1]ADRENTRY
}
type
  ADRENTRY = record
    ulReserved1: DWORD;
    cValues: DWORD;
    rgPropVals: Pointer;
  end;

  ADRLIST = record
    cEntries: DWORD;
    aEntries: array[0..0] of ADRENTRY;
  end;
const ADRENTRY = extern struct {
    ulReserved1: u32,
    cValues: u32,
    rgPropVals: ?*anyopaque,
};

const ADRLIST = extern struct {
    cEntries: u32,
    aEntries: [1]ADRENTRY,
};
type
  ADRENTRY {.bycopy.} = object
    ulReserved1: uint32
    cValues: uint32
    rgPropVals: pointer

  ADRLIST {.bycopy.} = object
    cEntries: uint32
    aEntries: array[1, ADRENTRY]
struct ADRENTRY
{
    uint ulReserved1;
    uint cValues;
    void* rgPropVals;
}

struct ADRLIST
{
    uint cEntries;
    ADRENTRY[1] aEntries;
}

HSP用 定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; ADRLIST サイズ: 16 バイト(x86)
dim st, 4    ; 4byte整数×4(構造体サイズ 16 / 4 切り上げ)
; cEntries : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; aEntries : ADRENTRY (+4, 12byte)  varptr(st)+4 を基点に操作(12byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; ADRLIST サイズ: 24 バイト(x64)
dim st, 6    ; 4byte整数×6(構造体サイズ 24 / 4 切り上げ)
; cEntries : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; aEntries : ADRENTRY (+8, 16byte)  varptr(st)+8 を基点に操作(16byte:入れ子/配列)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
; ※GUID・入れ子構造体はデフォルト型でないため、依存する #defstruct を先に定義(下記に同梱)。
#defstruct global ADRENTRY
    #field int ulReserved1
    #field int cValues
    #field intptr rgPropVals
#endstruct

#defstruct global ADRLIST
    #field int cEntries
    #field ADRENTRY aEntries 1
#endstruct

stdim st, ADRLIST        ; NSTRUCT 変数を確保
st->cEntries = 100
mes "cEntries=" + st->cEntries