Устаревшее описание функций в MSDN, не учитывающее 64-битность

05 Апр 2013

Автор: Андрей Карпов

MSDN является большой базой знаний, и как следствие поддержание ее в актуальном состоянии является крайне сложной и возможно почти неосуществимой задачей. Сейчас в форумах можно встретить вопросы программистов, занимающихся созданием 64-битных приложений и озадаченных описанием некоторых функций в MSDN.

В качестве примера можно привести обсуждение "MSDN 64-bit issue". На рисунке 1 изображен снимок экрана, на котором показано описание функции CListCtrl::SetItemData в on-line версии MSDN. Хотя эта заметка пишется в феврале 2010 года, описание функции до сих пор некорректно. И с высокой вероятностью можно утверждать, что многие другие материалы MSDN также пока не скорректированы с точки зрения 64-битности.

Рисунок 1 - Описание функции CListCtrl::SetItemData в MSDN Library On-line.

В описании функции CListCtrl::SetItemData изменен только аргумент. Тип параметра dwDara изменен с DWORD на DWORD_PTR. С описанием функции GetItemData ситуация аналогична. Возможно, эта замена делалась в неком автоматическом режиме на основании новых заголовочных файлов. А вот описание самих функций остались прежними и содержат упоминание "32-bit value".

Поставим следующий вопрос. Возможно, прототип функции изменен, но функция по-прежнему сохраняет только 32-бита информации? Можно ответить нет, основываясь на следующих обоснованиях:

1) Логическое обоснование. Часто нужно ассоциировать с элементом списка достаточно много данных. В этом случае данные объединяют в структуру и передают указатель на нее в функцию SetItemData. Разработчики Win64 API не могли лишить программистов такой возможности, а следовательно функция должна уметь хранить 64-битные указатели.

2) Практический эксперимент:

list.SetItemData(0, 0x1111111122222222ui64);
DWORD_PTR value = list.GetItemData(0);
if (value == 0x1111111122222222ui64)
  MessageBox(_T("OK"));

Успешный запуск этого кода в 64-битном приложении подтверждает, что SetItemData позволяет сохранять 64-битные значения.

Вывод. Описание SetItemData, GetItemData и ряда других функций в MSDN Library является устаревшим. Материалы в MSDN регулярно обновляются, и возможно описанная ошибка к настоящему моменту уже исправлена.

#64bit