HRESULT Method18([in] long cElems,
[in, out, size_is(cElems)] short *rgs);
Данный метод использует эффективность совместимого массива, и его гораздо проще использовать.
Приведенные выше примеры оперировали с одномерными массивами. Рассмотрим следующий прототип на С:
void g(short **arg1);
Этот прототип может означать в С все, что угодно. Возможно, функция ожидает указатель на одно короткое целое число:
void g(short **arg1) {
// return ptr to static
// возвращаем указатель на static
static short s;
*arg1 = &s;
}
Или, возможно, функция ожидает массив из 100 коротких указателей:
void g(short **arg1)
{
// square 100 shorts by ref
// квадрат из 100 коротких целых указателей
for (int n = 0; n < 100; n++)
*(arg1[n]) *= *(arg1[n]);
}
А также, возможно, функция ожидает указатель на указатель на массив коротких целых:
void g(short **arg1)
{
// square 100 shorts
// квадрат из 100 коротких целых
for (int n = 0; n < 100; n++)
(*arg1)[n] *= (*arg1)[n];
}
Этот синтаксический кошмар разрешается в IDL использованием такого синтаксиса, который часто побуждает пользователей-новичков бежать за утешением к документации.
Атрибуты IDL [size_is] и [lengtn_is] принимают переменное количество разделенных запятой аргументов, по одному на каждый уровень косвенности. Если параметр пропущен, то считается, что соответствующий уровень косвенности является указателем на экземпляр, а не на массив. Для того чтобы показать, что параметр является указателем на указатель на одиночный экземпляр, не требуется более никаких атрибутов:
HRESULT Method19([in] short **pps);
что означает такое расположение в памяти:
pps -> *pps-> **pps
Для того чтобы показать, что параметр является указателем на массив указателей на экземпляры, нужно написать следующий код IDL:
HRESULT Method20([in, size_is(3)] short **rgps);
что в памяти будет выглядеть примерно так:
rgps -> rgps[0] -> *rgps[0]
rgps[1] -> *rgps[1]
rgps[2] -> *rgps[2]
Для того чтобы показать, что параметр является указателем на указатель на массив экземпляров, следует написать такой код на IDL:
HRESULT Method21([in, size_is(,4)] short **pprgs);
что в памяти будет выглядеть следующим образом:
pprgs -> pprgs -> (pprgs)[0]
(pprgs)[1]
(pprgs)[2]
(pprgs)[3]
Для того чтобы показать, что параметр является массивом указателей на массивы экземпляров, нужно написать следующее:
HRESULT Method22([in, size_is(3,4)] short **rgrgs);
что в памяти будет выглядеть примерно так:
rgrgs -> rgrgs[0] -> rgrgs[0][0]
rgrgs[0][1]
rgrgs[0][2]
rgrgs[0][3]
rgrgs[1] -> rgrgs[1][0]
rgrgs[1][1]
rgrgs[1][2]
rgrgs[1][3]
rgrgs[2] -> rgrgs[2][0]
rgrgs[2][1]
rgrgs[2][2]
rgrgs[2][3]
Данный синтаксис, быть может, оставляет желать лучшего, тем не менее, он обладает большей гибкостью и меньшей неоднозначностью, чем на С.
Важно отметить, что приведенный выше метод IDL задает многомерный массив; формально он представляет собой массив указателей на массив указателей на экземпляры. Это не то же самое, что многомерный массив в языке С, который может быть определен в IDL с использованием стандартного синтаксиса С:
HRESULT Method23([in] short rgrgs[3][4]);
Данный синтаксис предполагает, что все элементы массива будут размещены в памяти непрерывно, что определенно не совпадает с предположением предыдущего примера.
Допускается задавать первое измерение многомерного массива с помощью атрибута [size_is]:
HRESULT Method24([in, size_is(3)] short rgrgs[][4]);
однако нельзя задавать никакого иного измерения, кроме крайнего левого.
Выражения, использованные атрибутами [size_is], [length_is] и другими атрибутами задания размерности массива, не могут быть размещены в вызовах функций. При этом, например, стал бы затруднительным маршалинг строк, соответствие и/или переменная длина которых размещены в вызовах функций wcslen или strlen. Это означает, что такой код в IDL является недопустимым:
HRESULT Method24([in, size_is(wcslen(wsz) + 1)] const OLECHAR *wsz);
Поскольку это ограничение сделало бы использование строк чрезвычайно неудобным для клиентских программ, IDL поддерживает строковый атрибут, который требует на уровне маршалинга вызывать соответствующую функцию xxxlen для вычисления соответствия массива. Ниже приведено правильное задание строки в качестве входного параметра:
HRESULT Method25([in, string] const OLECHAR *wsz);
или:
HRESULT Method26([in, string] const OLECHAR wsz[]);
При использовании строк в качестве выходных или входных/выходных параметров почти всегда целесообразно явно задавать длину буфера вызывающей программы, для гарантии того, что он будет достаточно большим на стороне сервера. Рассмотрим следующий полный ошибок код IDL:
HRESULT Method27([in, out, string] OLECHAR *pwsz);
Если вызывающая программа запускает этот метод с помощью достаточно короткой строки:
void f(IFoo *pFoo)
{
OLECHAR wsz[1024];
wcscpy(wsz, OLESTR(«Hello»));
pFoo->Method27(wsz);
// .. process updated string
// .. обрабатываем обновленную строку
}
то длина массива, размещенного на стороне сервера, будет вычислена, исходя из длины входной строки (эта длина равна шести с учетом заключительного нулевого символа). Рассмотрим следующую реализацию метода со стороны сервера:
HRESULT CFoo::Method27(OLECHAR *wsz)
{
DisplayString(wsz);
// wsz only can hold 6 characters!
// wsz может хранить только 6 символов!
wcscpy(wsz, OLESTR(«Goodbye»));
return S_OK;
}
Поскольку соответствие массива основывалось на величине wcslen(OLESTR(«Hello»)+1), то, когда реализация метода перезапишет в данную строку что-то более длинное, «хвост» этой строки перезапишет случайное число байтов памяти, что приведет к неисправимым ошибкам (будем надеяться, еще до выпуска данной программы в свет). Это означает, что, хотя вызывающая программа и имела достаточно памяти, заранее выделенной для записи результирующей строки, уровень маршалинга со стороны сервера не знал об этой кажущейся внешней памяти и выделил место, достаточное для хранения только шести символов строки Unicode. Код на IDL должен был быть таким:
HRESULT Method28([in] long cchMax, [in, out, string, size_is(cchMax)] OLECHAR *wsz);
а вызывающая программа могла бы использовать это так:
void f(IFoo *pFoo)
{
OLECHAR wsz[1024];
wcscpy(wsz, OLESTR(«Hello»));
pFoo->Method28(1024, wsz);
// .. process updated string
// .. обрабатываем обновленную строку
}
Наиболее неприятным аспектом примера c [in, out, string] является то, что он прекрасно работает, когда входная строка имеет по крайней мере такую же длину, как выходная строка. Ошибки, связанные с этим методом, будут периодическими и могут ни разу не возникнуть на стадии тестирования проекта.
В большинстве обычных API-функций, когда функция возвращает в вызывающую программу данные переменной длины, вызывающая программа заранее выделяет буфер для хранения результатов функции, а реализация функции заполняет буфер, заготовленный вызывающей программой. Ответственность за задание правильного размера буфера лежит на вызывающей программе. При использовании заданных вызывающей программой буферов для возвращения структур данных переменной длины (таких, как строки) может возникнуть проблема. Возможно, реализация метода захочет возвратить больше данных, чем ожидает вызывающая программа. Рассмотрим следующий код Windows SDK, который отображает текст редактирующего управляющего элемента, то есть текстового окна, позволяющего набирать и редактировать текст:
void Show(HWND hwndEdit)
{
TCHAR sz[1024];
GetWindowText(hwndEdit, sz, 1024);