mapi.util.php

<?php

/*
 * SPDX-License-Identifier: AGPL-3.0-only
 * SPDX-FileCopyrightText: Copyright 2005-2016 Zarafa Deutschland GmbH
 * SPDX-FileCopyrightText: Copyright 2020-2026 grommunio GmbH
 */

define('NOERROR', 0);
define('SECONDS_PER_DAY', 86400);
if (!defined('BLOCK_SIZE')) {
	define('BLOCK_SIZE', 1048576);
}

// Load all mapi defs
mapi_load_mapidefs(1);

/**
 * Function to make a MAPIGUID from a php string.
 * The C++ definition for the GUID is:
 *  typedef struct _GUID
 *  {
 *   unsigned long        Data1;
 *   unsigned short       Data2;
 *   unsigned short       Data3;
 *   unsigned char        Data4[8];
 *  } GUID;.
 *
 * A GUID is normally represented in the following form:
 *  {00062008-0000-0000-C000-000000000046}
 */
function makeGuid(string $guid): string {
	return pack("vvvv", hexdec(substr($guid, 5, 4)), hexdec(substr($guid, 1, 4)), hexdec(substr($guid, 10, 4)), hexdec(substr($guid, 15, 4))) . hex2bin(substr($guid, 20, 4)) . hex2bin(substr($guid, 25, 12));
}

/**
 * Function to get a human readable string from a MAPI error code.
 *
 * @return string The defined name for the MAPI error code
 */
function get_mapi_error_name(mixed $errcode = null): string {
	static $errorCache = null;

	if ($errcode === null) {
		$errcode = mapi_last_hresult();
	}

	if (strncasecmp((string) $errcode, '0x', 2) === 0) {
		$errcode = hexdec($errcode);
	}

	if ($errcode === 0) {
		return "NOERROR";
	}

	// Build cache on first call for performance
	if ($errorCache === null) {
		$errorCache = [];
		// Retrieve constants categories, MAPI error names are defined in gromox.
		foreach (get_defined_constants(true)['Core'] as $key => $value) {
			/*
			 * If PHP encounters a number beyond the bounds of the integer type,
			 * it will be interpreted as a float instead, so when comparing these error codes
			 * we have to manually typecast value to integer, so float will be converted in integer,
			 * but still its out of bound for integer limit so it will be auto adjusted to minus value
			 */
			if (strncmp($key, "MAPI_E_", 7) === 0 ||
				strncmp($key, "MAPI_W_", 7) === 0 ||
				strncmp($key, "ec", 2) === 0) {
				$errorCache[(int) $value] = $key;
			}
		}
	}

	if (isset($errorCache[$errcode])) {
		return $errorCache[$errcode];
	}

	// error code not found, return hex value (this is a fix for 64-bit systems, we can't use the dechex() function for this)
	$result = unpack("H*", pack("N", $errcode));

	return "0x" . $result[1];
}

/**
 * Parses properties from an array of strings. Each "string" may be either an ULONG, which is a direct property ID,
 * or a string with format "PT_TYPE:{GUID}:StringId" or "PT_TYPE:{GUID}:0xXXXX" for named
 * properties.
 */
function getPropIdsFromStrings(mixed $store, array $mapping): array {
	$props = [];

	$ids = ["name" => [], "id" => [], "guid" => [], "type" => []]; // this array stores all the information needed to retrieve a named property
	$num = 0;

	// caching
	$guids = [];

	foreach ($mapping as $name => $val) {
		if (is_string($val)) {
			$split = explode(":", $val);

			if (count($split) != 3) { // invalid string, ignore
				trigger_error(sprintf("Invalid property: %s \"%s\"", $name, $val), E_USER_NOTICE);

				continue;
			}

			if (str_starts_with($split[2], "0x")) {
				$id = hexdec(substr($split[2], 2));
			}
			elseif (preg_match('/^[1-9][0-9]{0,12}$/', $split[2])) {
				$id = (int) $split[2];
			}
			else {
				$id = $split[2];
			}

			// have we used this guid before?
			if (!defined($split[1])) {
				if (!array_key_exists($split[1], $guids)) {
					$guids[$split[1]] = makeGuid($split[1]);
				}
				$guid = $guids[$split[1]];
			}
			else {
				$guid = constant($split[1]);
			}

			// temp store info about named prop, so we have to call mapi_getidsfromnames just one time
			$ids["name"][$num] = $name;
			$ids["id"][$num] = $id;
			$ids["guid"][$num] = $guid;
			$ids["type"][$num] = $split[0];
			++$num;
		}
		else {
			// not a named property
			$props[$name] = $val;
		}
	}

	if (empty($ids["id"])) {
		return $props;
	}

	// get the ids
	$named = mapi_getidsfromnames($store, $ids["id"], $ids["guid"]);
	foreach ($named as $num => $prop) {
		$props[$ids["name"][$num]] = mapi_prop_tag(constant($ids["type"][$num]), mapi_prop_id($prop));
	}

	return $props;
}

/**
 * Check whether a call to mapi_getprops returned errors for some properties.
 * mapi_getprops function tries to get values of properties requested but somehow if
 * if a property value can not be fetched then it changes type of property tag as PT_ERROR
 * and returns error for that particular property, probable errors
 * that can be returned as value can be MAPI_E_NOT_FOUND, MAPI_E_NOT_ENOUGH_MEMORY.
 *
 * @return false|mixed Gives back false when there is no error, if there is, gives the error
 */
function propIsError(int $property, array $propArray): mixed {
	$errorTag = mapi_prop_tag(PT_ERROR, mapi_prop_id($property));

	return $propArray[$errorTag] ?? false;
}

/**
 * Note: Static function, more like a utility function.
 *
 * Gets all the items (including recurring items) in the specified calendar in the given timeframe. Items are
 * included as a whole if they overlap the interval <$start, $end> (non-inclusive). This means that if the interval
 * is <08:00 - 14:00>, the item [6:00 - 8:00> is NOT included, nor is the item [14:00 - 16:00>. However, the item
 * [7:00 - 9:00> is included as a whole, and is NOT capped to [8:00 - 9:00>.
 *
 * @param resource $store          The store in which the calendar resides
 * @param resource $calendar       The calendar to get the items from
 * @param int      $viewstart      Timestamp of beginning of view window
 * @param int      $viewend        Timestamp of end of view window
 * @param array    $propsrequested Array of properties to return
 *
 * @psalm-return list<mixed>
 */
function getCalendarItems(mixed $store, mixed $calendar, int $viewstart, int $viewend, array $propsrequested): array {
	$result = [];
	$properties = getPropIdsFromStrings($store, [
		"duedate" => "PT_SYSTIME:PSETID_Appointment:" . PidLidAppointmentEndWhole,
		"startdate" => "PT_SYSTIME:PSETID_Appointment:" . PidLidAppointmentStartWhole,
		"enddate_recurring" => "PT_SYSTIME:PSETID_Appointment:" . PidLidClipEnd,
		"recurring" => "PT_BOOLEAN:PSETID_Appointment:" . PidLidRecurring,
		"recurring_data" => "PT_BINARY:PSETID_Appointment:" . PidLidAppointmentRecur,
		"timezone_data" => "PT_BINARY:PSETID_Appointment:" . PidLidTimeZoneStruct,
		"label" => "PT_LONG:PSETID_Appointment:0x8214",
	]);

	// Create a restriction that will discard rows of appointments that are definitely not in our
	// requested time frame

	$table = mapi_folder_getcontentstable($calendar);

	$restriction =
		// OR
		[
			RES_OR,
			[
				[RES_AND,	// Normal items: itemEnd must be after viewStart, itemStart must be before viewEnd
					[
						[
							RES_PROPERTY,
							[
								RELOP => RELOP_GT,
								ULPROPTAG => $properties["duedate"],
								VALUE => $viewstart,
							],
						],
						[
							RES_PROPERTY,
							[
								RELOP => RELOP_LT,
								ULPROPTAG => $properties["startdate"],
								VALUE => $viewend,
							],
						],
					],
				],
				// OR
				[
					RES_PROPERTY,
					[
						RELOP => RELOP_EQ,
						ULPROPTAG => $properties["recurring"],
						VALUE => true,
					],
				],
			],	// EXISTS OR
		];		// global OR

	// Get requested properties, plus whatever we need
	$proplist = [PR_ENTRYID, $properties["recurring"], $properties["recurring_data"], $properties["timezone_data"], PR_SUBJECT];
	$proplist = array_merge($proplist, $propsrequested);

	// Restricting the table filters it while it loads; passing the
	// restriction to queryallrows instead walks it row by row.
	mapi_table_restrict($table, $restriction, TBL_BATCH);
	$rows = mapi_table_queryallrows($table, $proplist);

	// $rows now contains all the items that MAY be in the window; a recurring item needs expansion before including in the output.

	foreach ($rows as $row) {
		$items = [];

		if (isset($row[$properties["recurring"]]) && $row[$properties["recurring"]]) {
			// Recurring item
			$rec = new Recurrence($store, $row);

			// GetItems guarantees that the item overlaps the interval <$viewstart, $viewend>
			try {
				$occurrences = $rec->getItems($viewstart, $viewend);
				foreach ($occurrences as $occurrence) {
					// The occurrence takes all properties from the main row, but overrides some properties (like start and end obviously)
					$item = $occurrence + $row;
					$items[] = $item;
				}
			}
			catch (RecurrenceException $re) {
				error_log(sprintf(
					"getCalendarItems RecurrenceException (%d) for item '%s' - %s - %s",
					$re->getCode(),
					$row[PR_SUBJECT] ?? '<empty subject>',
					bin2hex($row[PR_ENTRYID]),
					bin2hex($row[$properties["recurring_data"]])
				));
				$re->setHandled();
			}
		}
		else {
			// Normal item, it matched the search criteria and therefore overlaps the interval <$viewstart, $viewend>
			$items[] = $row;
		}

		$result = array_merge($result, $items);
	}

	// All items are guaranteed to overlap the interval <$viewstart, $viewend>. Note that we may be returning a few extra
	// properties that the caller did not request (recurring, etc). This shouldn't be a problem though.
	return $result;
}

/**
 * Compares two entryIds. It is possible to have two different entryIds that should match as they
 * represent the same object (in multiserver environments).
 *
 * @return bool Result of the comparison
 */
function compareEntryIds(mixed $entryId1, mixed $entryId2): bool {
	if (!is_string($entryId1) || !is_string($entryId2)) {
		return false;
	}

	// if normal comparison succeeds then we can directly say that entryids are same
	return $entryId1 === $entryId2;
}

/**
 * Creates a goid from an ical uuid.
 *
 * @return string binary string representation of goid
 */
function getGoidFromUid(string $uid): string {
	return hex2bin("040000008200E00074C5B7101A82E0080000000000000000000000000000000000000000" .
				bin2hex(pack("V", 12 + strlen($uid)) . "vCal-Uid" . pack("V", 1) . $uid));
}

/**
 * Returns zero terminated goid. It is required for backwards compatibility.
 *
 * @return string an OL compatible GlobalObjectID
 */
function getGoidFromUidZero(string $uid): string {
	// uids longer than 64 chars are only passed through as hex encoded goids
	// if they actually are valid hex
	if (strlen($uid) > 64 && ctype_xdigit($uid) && strlen($uid) % 2 == 0) {
		return hex2bin($uid);
	}

	return hex2bin("040000008200E00074C5B7101A82E0080000000000000000000000000000000000000000" .
		bin2hex(pack("V", 13 + strlen($uid)) . "vCal-Uid" . pack("V", 1) . $uid) . "00");
}

/**
 * Creates an ical uuid from a goid.
 *
 * @return null|string ical uuid
 */
function getUidFromGoid(string $goid): ?string {
	// check if "vCal-Uid" is somewhere in outlookid case-insensitive
	$uid = stristr($goid, "vCal-Uid");
	if ($uid !== false) {
		// get the length of the ical id - go back 4 position from where "vCal-Uid" was found
		$begin = unpack("V", substr($goid, strlen($uid) * (-1) - 4, 4));

		// remove "vCal-Uid" and packed "1" and use the ical id length
		return trim(substr($uid, 12, $begin[1] - 12));
	}

	return null;
}

/**
 * Converts a MAPI property tag into a human readable value.
 *
 * This depends on the definition of the property tag in core
 *
 * @example prop2Str(0x0037001e) => 'PR_SUBJECT'
 *
 * @return string the symbolic name of the property tag
 */
function prop2Str(mixed $property): string {
	static $propertyCache = null;

	if (is_int($property)) {
		// Build cache on first call for performance
		if ($propertyCache === null) {
			$propertyCache = [];
			foreach (get_defined_constants(true)['Core'] as $key => $value) {
				if (str_starts_with($key, 'PR_')) {
					$propertyCache[$value] = $key;
				}
			}
		}

		return $propertyCache[$property] ?? sprintf("0x%08X", $property);
	}

	return $property;
}

/**
 * Converts RELOP constant to human readable string.
 */
function relOpToString(int $relOp): string {
	return match ($relOp) {
		RELOP_LT => "RELOP_LT",
		RELOP_LE => "RELOP_LE",
		RELOP_GT => "RELOP_GT",
		RELOP_GE => "RELOP_GE",
		RELOP_EQ => "RELOP_EQ",
		RELOP_NE => "RELOP_NE",
		RELOP_RE => "RELOP_RE",
		default => "",
	};
}

/**
 * Converts content restriction flags into a human readable string.
 */
function fuzzyLevelToString(mixed $fuzzyLevel): string {
	if (($fuzzyLevel & FL_SUBSTRING) == FL_SUBSTRING) {
		$levels = "FL_SUBSTRING";
	}
	elseif (($fuzzyLevel & FL_PREFIX) == FL_PREFIX) {
		$levels = "FL_PREFIX";
	}
	else {
		$levels = "FL_FULLSTRING";
	}

	if (($fuzzyLevel & FL_IGNORECASE) == FL_IGNORECASE) {
		$levels .= " | FL_IGNORECASE";
	}
	if (($fuzzyLevel & FL_IGNORENONSPACE) == FL_IGNORENONSPACE) {
		$levels .= " | FL_IGNORENONSPACE";
	}
	if (($fuzzyLevel & FL_LOOSE) == FL_LOOSE) {
		$levels .= " | FL_LOOSE";
	}

	return $levels;
}

/**
 * Converts BMR constant to human readable string.
 */
function bitmaskTypeToString(mixed $maskType): string {
	// relop flags
	$maskTypeFlags = "";
	if ($maskType == BMR_EQZ) {
		$maskTypeFlags = "BMR_EQZ";
	}
	elseif ($maskType == BMR_NEZ) {
		$maskTypeFlags = "BMR_NEZ";
	}

	return $maskTypeFlags;
}

/**
 * Returns the value of a restriction property, given directly or as a property array.
 */
function restrictionPropValue(mixed $propTag, mixed $propValue): mixed {
	return is_array($propValue) ? $propValue[$propTag] : $propValue;
}

/**
 * Converts the properties of a RES_COMMENT into human readable form.
 */
function simplifyCommentProps(mixed $props): mixed {
	foreach ($props as &$prop) {
		$propTag = $prop[ULPROPTAG];
		$propValue = $prop[VALUE];

		$prop = [
			"ULPROPTAG" => prop2Str($propTag),
			"VALUE" => restrictionPropValue($propTag, $propValue),
		];
	}
	unset($prop);

	return $props;
}

/**
 * Converts the operands of a RES_AND or RES_OR.
 */
function simplifyRestrictionOperands(array &$restriction): void {
	if (isset($restriction[1][0]) && is_array($restriction[1][0])) {
		foreach ($restriction[1] as &$res) {
			$res = simplifyRestriction($res);
		}
		unset($res);
	}
	elseif (isset($restriction[1]) && $restriction[1]) {
		$restriction[1] = simplifyRestriction($restriction[1]);
	}
}

/**
 * Converts the constants of a restriction on a property into human readable strings.
 */
function simplifyPropertyRestriction(array $restriction): array {
	switch ($restriction[0]) {
		case RES_PROPERTY:
			$restriction[0] = "RES_PROPERTY";
			$propTag = $restriction[1][ULPROPTAG];
			$propValue = $restriction[1][VALUE];
			$relOp = $restriction[1][RELOP];

			unset($restriction[1]);

			$restriction[1]["RELOP"] = relOpToString($relOp);
			$restriction[1]["ULPROPTAG"] = prop2Str($propTag);
			$restriction[1]["VALUE"] = restrictionPropValue($propTag, $propValue);
			break;

		case RES_CONTENT:
			$restriction[0] = "RES_CONTENT";
			$propTag = $restriction[1][ULPROPTAG];
			$propValue = $restriction[1][VALUE];
			$fuzzyLevel = $restriction[1][FUZZYLEVEL];

			unset($restriction[1]);

			$restriction[1]["FUZZYLEVEL"] = fuzzyLevelToString($fuzzyLevel);
			$restriction[1]["ULPROPTAG"] = prop2Str($propTag);
			$restriction[1]["VALUE"] = restrictionPropValue($propTag, $propValue);
			break;

		case RES_COMPAREPROPS:
			$propTag1 = $restriction[1][ULPROPTAG1];
			$propTag2 = $restriction[1][ULPROPTAG2];

			unset($restriction[1]);

			$restriction[1]["ULPROPTAG1"] = prop2Str($propTag1);
			$restriction[1]["ULPROPTAG2"] = prop2Str($propTag2);
			break;

		case RES_BITMASK:
			$restriction[0] = "RES_BITMASK";
			$propTag = $restriction[1][ULPROPTAG];
			$maskType = $restriction[1][ULTYPE];
			$maskValue = $restriction[1][ULMASK];

			unset($restriction[1]);

			$maskTypeFlags = bitmaskTypeToString($maskType);

			$restriction[1]["ULPROPTAG"] = prop2Str($propTag);
			$restriction[1]["ULTYPE"] = $maskTypeFlags;
			$restriction[1]["ULMASK"] = $maskValue;
			break;

		case RES_SIZE:
			$restriction[0] = "RES_SIZE";
			$propTag = $restriction[1][ULPROPTAG];
			$propValue = $restriction[1][CB];
			$relOp = $restriction[1][RELOP];

			unset($restriction[1]);

			$restriction[1]["ULPROPTAG"] = prop2Str($propTag);
			$restriction[1]["RELOP"] = relOpToString($relOp);
			$restriction[1]["CB"] = $propValue;
			break;

		case RES_EXIST:
			$propTag = $restriction[1][ULPROPTAG];

			unset($restriction[1]);

			$restriction[1]["ULPROPTAG"] = prop2Str($propTag);
			break;
	}

	return $restriction;
}

/**
 * Converts all constants of restriction into a human readable strings.
 */
function simplifyRestriction(mixed $restriction): mixed {
	if (!is_array($restriction)) {
		return $restriction;
	}

	$type = $restriction[0];

	switch ($type) {
		case RES_AND:
		case RES_OR:
			$restriction[0] = $type == RES_AND ? "RES_AND" : "RES_OR";
			simplifyRestrictionOperands($restriction);
			break;

		case RES_NOT:
			$restriction[0] = "RES_NOT";
			$restriction[1][0] = simplifyRestriction($restriction[1][0]);
			break;

		case RES_COMMENT:
			$restriction[0] = "RES_COMMENT";
			$res = simplifyRestriction($restriction[1][RESTRICTION]);
			$props = simplifyCommentProps($restriction[1][PROPS]);

			unset($restriction[1]);

			$restriction[1]["RESTRICTION"] = $res;
			$restriction[1]["PROPS"] = $props;
			break;

		case RES_SUBRESTRICTION:
			$propTag = $restriction[1][ULPROPTAG];
			$res = simplifyRestriction($restriction[1][RESTRICTION]);

			unset($restriction[1]);

			$restriction[1]["ULPROPTAG"] = prop2Str($propTag);
			$restriction[1]["RESTRICTION"] = $res;
			break;

		default:
			$restriction = simplifyPropertyRestriction($restriction);
			break;
	}

	return $restriction;
}

/**
 * Helper to stream a MAPI property.
*/
function readMapiPropStream(mixed $mapiobj, int $proptag): string {
	$stream = mapi_openproperty($mapiobj, $proptag, IID_IStream, 0, 0);
	if ($stream === false) {
		return '';
	}
	$stat = mapi_stream_stat($stream);
	mapi_stream_seek($stream, 0, STREAM_SEEK_SET);

	// A read may return less than a full block, so count bytes rather than
	// iterations: advancing by BLOCK_SIZE regardless returns a short value.
	$datastring = '';
	while (strlen($datastring) < $stat['cb']) {
		$chunk = mapi_stream_read($stream, BLOCK_SIZE);
		if ($chunk === false || $chunk === '') {
			break;
		}

		$datastring .= $chunk;
	}

	// The caller cannot tell a short value from a complete one, so say so here.
	if (strlen($datastring) < $stat['cb']) {
		error_log(sprintf(
			"readMapiPropStream(): property 0x%08X is truncated, read %d of %d bytes",
			$proptag,
			strlen($datastring),
			$stat['cb']
		));
	}

	return $datastring;
}

/**
 * Helper to write a MAPI property through a stream.
 */
function writeMapiPropStream(mixed $mapiobj, int $proptag, string $data): bool {
	$stream = mapi_openproperty($mapiobj, $proptag, IID_IStream, STGM_TRANSACTED, MAPI_CREATE | MAPI_MODIFY);
	if ($stream === false) {
		return false;
	}
	$length = strlen($data);
	if (!mapi_stream_setsize($stream, $length)) {
		return false;
	}
	if (mapi_stream_write($stream, $data) !== $length) {
		return false;
	}

	return mapi_stream_commit($stream);
}

/**
 * Whether mapi_getprops() reported $property as too large to be returned inline.
 */
function propIsTooLarge(int $property, array $propArray): bool {
	$error = propIsError($property, $propArray);

	// php-mapi reports the code unsigned, older builds signed
	return $error !== false && ((int) $error & 0xFFFFFFFF) === (MAPI_E_NOT_ENOUGH_MEMORY & 0xFFFFFFFF);
}

/**
 * Value of $proptag from a mapi_getprops() result, streamed when it was too
 * large for the result. null when the property is not set.
 */
function readMapiProp(mixed $mapiobj, int $proptag, array $propArray): mixed {
	if (isset($propArray[$proptag])) {
		return $propArray[$proptag];
	}

	return propIsTooLarge($proptag, $propArray) ? readMapiPropStream($mapiobj, $proptag) : null;
}

/**
 * Parses a PidLidAppointmentTimeZoneDefinition* blob (MS-OXOCAL 2.2.1.41).
 *
 * @return array empty when the blob is missing or truncated
 */
function parseTimezoneDefinition(?string $tzdef): array {
	if ($tzdef === null || strlen($tzdef) < 8) {
		return [];
	}

	$res = unpack("Cmajorver/Cminorver/vcbheader/vreserved/vcchkeyname", $tzdef);
	$offset = 8;
	$cchKeyName = $res['cchkeyname'] * 2;
	if (strlen($tzdef) < $offset + $cchKeyName + 2) {
		return [];
	}
	$data = unpack("a{$cchKeyName}keyname/vcrules", substr($tzdef, $offset, $cchKeyName + 2));
	$res['keyname'] = $data['keyname'];
	$res['crules'] = $data['crules'];
	$res['rules'] = [];
	$offset += $cchKeyName + 2;

	for ($i = 0; $i < $res['crules']; ++$i) {
		if (strlen($tzdef) < $offset + 66) {
			return [];
		}
		$rule = unpack("Cmajorver/Cminorver/vreserved/vtzruleflags/vwyear/a14x/lbias/lstdbias/ldstbias", substr($tzdef, $offset, 34));
		$offset += 34;
		$rule['stStandardDate'] = unpack("vyear/vmonth/vdayofweek/vday/vhour/vminute/vsecond/vmiliseconds", substr($tzdef, $offset, 16));
		$offset += 16;
		$rule['stDaylightDate'] = unpack("vyear/vmonth/vdayofweek/vday/vhour/vminute/vsecond/vmiliseconds", substr($tzdef, $offset, 16));
		$offset += 16;
		$res['rules'][] = $rule;
	}

	return $res;
}

/**
 * The rule flagged TZRULE_FLAG_EFFECTIVE_TZREG of a parsed timezone definition.
 */
function getEffectiveTimezoneRule(array $tzdef): ?array {
	foreach ($tzdef['rules'] ?? [] as $rule) {
		if ($rule['tzruleflags'] & TZRULE_FLAG_EFFECTIVE_TZREG) {
			return $rule;
		}
	}

	return null;
}

/**
 * iconv charset name for a Windows codepage, iso-8859-15 when the codepage is
 * unknown or has no name this iconv resolves. Built from gromox' cpid.txt with
 * glibc spellings; 936 maps to GB18030, the superset of gbk.
 */
function getCodepageCharset(int $codepage): string {
	static $codepages = [
		37 => "IBM037",
		437 => "IBM437",
		500 => "IBM500",
		708 => "ASMO-708",
		775 => "ibm775",
		850 => "ibm850",
		852 => "ibm852",
		855 => "IBM855",
		857 => "ibm857",
		858 => "IBM858",
		860 => "IBM860",
		861 => "ibm861",
		862 => "IBM862",
		863 => "IBM863",
		864 => "IBM864",
		865 => "IBM865",
		866 => "cp866",
		869 => "ibm869",
		870 => "IBM870",
		874 => "windows-874",
		875 => "IBM875",
		932 => "shift_jis",
		936 => "GB18030",
		949 => "cp949",
		950 => "big5",
		1026 => "IBM1026",
		1047 => "IBM1047",
		1140 => "IBM1140",
		1141 => "IBM1141",
		1142 => "IBM1142",
		1143 => "IBM1143",
		1144 => "IBM1144",
		1145 => "IBM1145",
		1146 => "IBM1146",
		1147 => "IBM1147",
		1148 => "IBM1148",
		1149 => "IBM1149",
		1200 => "UTF-16",
		1201 => "UTF-16BE",
		1250 => "windows-1250",
		1251 => "windows-1251",
		1252 => "windows-1252",
		1253 => "windows-1253",
		1254 => "windows-1254",
		1255 => "windows-1255",
		1256 => "windows-1256",
		1257 => "windows-1257",
		1258 => "windows-1258",
		1361 => "Johab",
		10000 => "MACINTOSH",
		10007 => "MAC-CYRILLIC",
		10017 => "MAC-UK",
		10029 => "MAC-CENTRALEUROPE",
		10079 => "MAC-IS",
		12000 => "UTF-32",
		12001 => "UTF-32BE",
		20000 => "EUC-TW",
		20106 => "DIN_66003",
		20107 => "SEN_850200_B",
		20108 => "NS_4551-1",
		20127 => "us-ascii",
		20261 => "T.61-8BIT",
		20269 => "ISO_6937",
		20273 => "IBM273",
		20277 => "IBM277",
		20278 => "IBM278",
		20280 => "IBM280",
		20284 => "IBM284",
		20285 => "IBM285",
		20290 => "IBM290",
		20297 => "IBM297",
		20420 => "IBM420",
		20423 => "IBM423",
		20424 => "IBM424",
		20866 => "koi8-r",
		20871 => "IBM871",
		20880 => "IBM880",
		20905 => "IBM905",
		20932 => "EUC-JP",
		20936 => "GB2312",
		20949 => "EUC-KR",
		21025 => "IBM1025",
		21866 => "koi8-u",
		28591 => "iso-8859-1",
		28592 => "iso-8859-2",
		28593 => "iso-8859-3",
		28594 => "iso-8859-4",
		28595 => "iso-8859-5",
		28596 => "iso-8859-6",
		28597 => "iso-8859-7",
		28598 => "iso-8859-8",
		28599 => "iso-8859-9",
		28603 => "iso-8859-13",
		28605 => "iso-8859-15",
		38598 => "ISO-8859-8",
		50220 => "iso-2022-jp",
		50221 => "csISO2022JP",
		50222 => "iso-2022-jp",
		50225 => "iso-2022-kr",
		50227 => "ISO-2022-CN",
		51932 => "euc-jp",
		51936 => "EUC-CN",
		51949 => "euc-kr",
		54936 => "GB18030",
		65000 => "utf-7",
		65001 => "utf-8",
	];

	// West-European mails are the ones most likely to carry a wrong codepage,
	// and utf-8 is binary compatible with the lower 7 bits of iso-8859-15.
	return $codepages[$codepage] ?? "iso-8859-15";
}

/**
 * Restriction for the appointments of a calendar that touch <$start, $end>,
 * recurring series included. $props holds the resolved tags for "starttime",
 * "endtime", "isrecurring" and "recurrenceend".
 */
function getCalendarRestriction(array $props, int $start, int $end): array {
	return [RES_OR, [
		// item.end >= start && item.start <= end
		[RES_AND, [
			[RES_PROPERTY, [RELOP => RELOP_LE, ULPROPTAG => $props["starttime"], VALUE => $end]],
			[RES_PROPERTY, [RELOP => RELOP_GE, ULPROPTAG => $props["endtime"], VALUE => $start]],
		]],
		// recurring series that still runs at start
		[RES_AND, [
			[RES_EXIST, [ULPROPTAG => $props["recurrenceend"]]],
			[RES_PROPERTY, [RELOP => RELOP_EQ, ULPROPTAG => $props["isrecurring"], VALUE => true]],
			[RES_PROPERTY, [RELOP => RELOP_GE, ULPROPTAG => $props["recurrenceend"], VALUE => $start]],
		]],
		// open-ended recurring series that started before end
		[RES_AND, [
			[RES_NOT, [[RES_EXIST, [ULPROPTAG => $props["recurrenceend"]]]]],
			[RES_PROPERTY, [RELOP => RELOP_LE, ULPROPTAG => $props["starttime"], VALUE => $end]],
			[RES_PROPERTY, [RELOP => RELOP_EQ, ULPROPTAG => $props["isrecurring"], VALUE => true]],
		]],
	]];
}

/**
 * PidLidForwardNotificationRecipients of a meeting forward notification, a
 * RecipientRow list as in MS-OXOCAL v22.1 §2.2.1.25. Each row carries the
 * SMTP address and the name and no further properties.
 *
 * @param array $addresses SMTP addresses
 * @param array $names     display names, by the index of $addresses
 */
function packForwardNotificationRecipients(array $addresses, array $names): string {
	$utf16 = static fn (string $s): string => (string) iconv('UTF-8', 'UTF-16LE', $s) . "\0\0";
	// SMTP type, E, D and U flags
	$flags = 0x0003 | 0x0008 | 0x0010 | 0x0200;
	$rows = '';
	foreach (array_values($addresses) as $i => $smtp) {
		$name = (string) ($names[$i] ?? '');
		$rows .= pack('v', $flags) . $utf16((string) $smtp) .
			$utf16($name !== '' ? $name : (string) $smtp) . pack('vC', 0, 0);
	}

	return pack('VV', 1, count($addresses)) . $rows;
}

/**
 * The recipients in a PidLidForwardNotificationRecipients value. Rows that
 * carry properties end the list, as their size depends on columns the value
 * does not name.
 *
 * @return array rows of [address type, address, display name]
 */
function unpackForwardNotificationRecipients(string $blob): array {
	$len = strlen($blob);
	$pos = 8;
	if ($len < $pos || unpack('V', $blob)[1] != 1) {
		return [];
	}
	$str8 = static function () use ($blob, &$pos): ?string {
		$end = strpos($blob, "\0", $pos);
		if ($end === false) {
			return null;
		}
		$s = substr($blob, $pos, $end - $pos);
		$pos = $end + 1;

		return $s;
	};
	$wstr = static function () use ($blob, $len, &$pos): ?string {
		for ($end = $pos; $end + 1 < $len; $end += 2) {
			if ($blob[$end] === "\0" && $blob[$end + 1] === "\0") {
				$s = (string) iconv('UTF-16LE', 'UTF-8', substr($blob, $pos, $end - $pos));
				$pos = $end + 2;

				return $s;
			}
		}

		return null;
	};
	$u16 = static function () use ($blob, $len, &$pos): ?int {
		if ($pos + 2 > $len) {
			return null;
		}
		$v = unpack('v', $blob, $pos)[1];
		$pos += 2;

		return $v;
	};

	$rows = [];
	for ($n = unpack('V', $blob, 4)[1]; $n > 0; --$n) {
		$flags = $u16();
		if ($flags === null) {
			break;
		}
		$type = $flags & 0x0007;
		$string = $flags & 0x0200 ? $wstr : $str8;
		$addrtype = match ($type) {
			0x1 => 'EX',
			0x3 => 'SMTP',
			default => '',
		};
		$addr = null;
		if ($type == 0x1) {
			// prefix length and display type, the DN is whole only without a prefix
			if ($pos + 2 > $len) {
				break;
			}
			$prefix = ord($blob[$pos]);
			$pos += 2;
			$addr = $str8();
			if ($addr === null) {
				break;
			}
			if ($prefix != 0) {
				$addr = null;
			}
		}
		elseif ($type == 0x6 || $type == 0x7) {
			// entryid and search key
			for ($i = 0; $i < 2; ++$i) {
				$size = $u16();
				if ($size === null || $pos + $size > $len) {
					break 2;
				}
				$pos += $size;
			}
		}
		if ($type == 0x0 && $flags & 0x8000) {
			$addrtype = $str8();
			if ($addrtype === null) {
				break;
			}
		}
		$fields = [];
		foreach ([0x0008, 0x0010, 0x0400, 0x0020] as $bit) {
			if (!($flags & $bit)) {
				$fields[$bit] = null;

				continue;
			}
			$fields[$bit] = $string();
			if ($fields[$bit] === null) {
				break 2;
			}
		}
		$addr ??= $fields[0x0008];
		$name = $fields[0x0010] ?? $fields[0x0020] ?? $fields[0x0400] ?? '';
		$columns = $u16();
		if ($columns === null) {
			break;
		}
		if ($addr !== null && $addr !== '') {
			$rows[] = [$addrtype, $addr, $name];
		}
		if ($columns != 0 || $pos >= $len) {
			break;
		}
		// the flag byte of the empty property row
		++$pos;
	}

	return $rows;
}