Структуры (RPC)

Статья
06/13/2023

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

Простая структура
Простая структура с указателями
Структура соответствия
Соответствующая структура с указателями
Соответствующая разнообразная структура (с указателями или без нее)
Жесткая структура
Сложная структура
Описание макета элемента структуры

Примечание.

По сравнению с категориями массивов становится ясно, что можно описать только структуры размером до 64 кб (размер находится для плоской части структуры), то есть массивы SM и LG не эквивалентны.

Элементы, общие для структур

Трассы

Необходимое выравнивание буфера перед отменой структуры. Допустимые значения: 0, 1, 3 и 7 (фактическое выравнивание минус 1).
memory_size

Размер структуры в памяти в байтах; для соответствующих структур этот размер не включает размер массива.
offset_to_array_description

Смещение от текущего указателя строки формата к описанию соответствующего массива, содержащегося в структуре.
member_layout

Описание каждого элемента структуры. Подпрограммы NDR должны проверять только эту часть строки формата типа, если требуется преобразование endian или если тип является сложной структурой.
pointer_layout

См. раздел "Макет указателя ".

Простая структура

Простая структура содержит только базовые типы, фиксированные массивы и другие простые структуры. Основная особенность простой структуры заключается в том, что она может быть блочного копирования в целом.

FC_STRUCT alignment<1> 
memory_size<2> 
member_layout<> 
FC_END

Простая структура с указателями

Простая структура с указателями содержит только базовые типы, указатели, фиксированные массивы, простые структуры и другие простые структуры с указателями. Так как макет<> должен быть доступен только при преобразовании эндианности, он помещается в конец описания.

FC_PSTRUCT alignment<1> 
memory_size<2> 
pointer_layout<> 
member_layout<> 
FC_END

Структура соответствия

Соответствующая структура содержит только базовые типы, фиксированные массивы и простые структуры, а также должна содержать соответствующую строку или соответствующий массив. Этот массив может содержаться в другой соответствующей структуре или соответствующей структуре с указателями, внедренными в эту структуру.

FC_CSTRUCT alignment<1> 
memory_size<2> 
offset_to_array_description<2> 
member_layout<> 
FC_END

Соответствующая структура с указателями

Соответствующая структура с указателями содержит только базовые типы, указатели, фиксированные массивы, простые структуры и простые структуры с указателями; Соответствующая структура должна содержать соответствующий массив. Этот массив может содержаться в другой соответствующей структуре или соответствующей структуре с указателями, внедренными в эту структуру.

FC_CPSTRUCT alignment<1> 
memory_size<2> 
offset_to_array_description<2> 
pointer_layout<> 
member_layout<> FC_END

Соответствующая разнообразная структура (с указателями или без нее)

Соответствующая разнообразная структура содержит только простые типы, указатели, фиксированные массивы, простые структуры и простые структуры с указателями; Соответствующая структура должна содержать соответствующую строку или соответствующий массив. Соответствующая строка или массив фактически может содержаться в другой соответствующей структуре или соответствующей структуре с указателями, внедренными в эту структуру.

FC_CVSTRUCT alignment<1> 
memory_size<2> 
offset_to_array_description<2> 
[pointer_layout<>] 
layout<> 
FC_END

Жесткая структура

Жесткая структура — это концепция, направленная на устранение крутых штрафов, связанных с обработкой сложных структур. Он является производным от наблюдения, что сложная структура обычно имеет только одно или два условия, которые препятствуют блочного копирования, и поэтому портят его производительность по сравнению с простой структурой. Виновниками обычно являются профсоюзы или поля перечисления.

Жесткая структура — это структура, которая содержит перечисление16, конечную заполнение в памяти или объединение в качестве последнего элемента. Эти три элемента препятствуют переходу структуры в одну из предыдущих категорий структур, которые пользуются небольшими затратами на интерпретацию и максимальным потенциалом оптимизации, но не заставлять его в очень затратную категорию структуры.

Перечисление16 не должно привести к различиям размеров памяти и провода структуры. Структура не может иметь ни соответствующий массив, ни какие-либо указатели (если только часть объединения); единственными допустимыми являются базовые типы, фиксированные массивы и простые структуры.

FC_HARD_STRUCTURE alignment<1> 
memory_size<2> 
reserved<4> 
enum_offset<2> 
copy_size<2> 
mem_copy_incr<2> 
union_description_offset<2>
member_layout<> 
FC_END

Поле enum_offset 2> предоставляет смещение от начала структуры в памяти до перечисления16, если оно содержит одно; в противном случае поле enum_offset<<2> равно –1.

Поле copy_size<2> предоставляет общее количество байтов в структуре, которое может быть блочное копирование в буфер или из нее. Этот общий объем не включает в себя ни одно конечное объединение, ни конечную заполнение в памяти. Это значение также является объемом указателя буфера, который следует увеличить после копирования.

Поле mem_copy_incr<2> — это число байтов, которые указатель памяти следует увеличить после блокировки копирования перед обработкой любого конечного объединения. Приращение к этому объему (не по copy_size<2> байта) дает правильный указатель памяти на любой конечный союз.

Сложная структура

Сложная структура — это любая структура, содержащая одно или несколько полей, которые либо препятствуют копированию структуры, либо для которой во время маршалинга или отмены маршалинга необходимо выполнить дополнительную проверка (например, привязанные проверка к перечислению). Следующие типы NDR попадают в эту категорию:

простые типы: ENUM16, __INT3264 (только на 64-разрядных платформах), целочисленный с [диапазоном]
Выравнивание заполнения в конце структуры
указатели интерфейса (они используют внедренный комплекс)
игнорируемые указатели (связанные с атрибутом [игнорировать] и маркером FC_IGNORE)
сложные массивы, различные массивы, строковые массивы
многомерные массивы соответствия с по крайней мере одним нефиксным измерением
Союзов
элементы, определенные с помощью [transmit_as], [represent_as], [wire_marshal], [user_marshal]
внедренные сложные структуры
заполнение в конце структуры

Сложная структура содержит следующее описание формата:

FC_BOGUS_STRUCT alignment<1> 
memory_size<2> 
offset_to_conformant_array_description<2> 
offset_to_pointer_layout<2> 
member_layout<> 
FC_END 
[pointer_layout<>]

Поле memory_size<2> — это размер структуры в памяти в байтах.

Если структура содержит соответствующий массив, поле offset_to_conformant_array_description<2> предоставляет смещение к описанию соответствующего массива, в противном случае оно равно нулю.

Если структура содержит указатели, поле offset_to_pointer_layout<2> предоставляет смещение после макета структуры в макет указателя, в противном случае это поле равно нулю.

Поле pointer_layout<> сложной структуры обрабатывается несколько иначе, чем для других структур. Поле pointer_layout<> сложной структуры содержит только описания фактических полей указателя в самой структуре. Все указатели, содержащиеся в любых внедренных массивах, объединениях или структурах, не описываются в поле pointer_layout<> сложной структуры.

Примечание.

Это отличается от других структур, которые дублируют описание любых указателей, содержащихся в внедренных массивах или структурах в собственном _layout поле указателя<> .

Формат макета указателя сложной структуры также существенно отличается. Так как он содержит только описания фактических элементов указателя, так как сложная структура маршалируется и немаршалируется по одному полю за раз, поле pointer_layout<> просто содержит описание указателя всех элементов указателя. Нет начальных FC_PP, и ни одна из обычных pointer_layout<> информации.

Описание макета элемента структуры

Описание макета структуры содержит один или несколько следующих символов формата:

Любой из символов базового типа, например FC_CHAR, и т. д.
Директивы выравнивания. Существует три символа формата, указывающие выравнивание указателя памяти: FC_ALIGNM2, FC_ALIGNM4 и FC_ALIGNM8.

Примечание.

Существуют также маркеры выравнивания буфера, FC_ALIGNB2 через FC_ALIGNM8; они не используются.
Заполнение памяти. Они происходят только в конце описания структуры и указывают количество байтов заполнения в памяти до соответствующего массива в структуре: FC_STRUCTPADn, где n — количество байтов заполнения.
Любой внедренный тип небазы (обратите внимание, что соответствующий массив никогда не встречается в макете структуры). Это описание 4-байтов:
```
FC_EMBEDDED_COMPLEX memory_pad<1> 
offset_to_description<2>,
```
если смещение не гарантируется выравниванием по 2 байтам.

<memory_pad 1> — это заполнение, необходимое в памяти перед сложным полем.

<offset_to_description 2> — это смещение относительного типа внедренного типа.

Кроме того, может быть FC_PAD перед завершением FC_END при необходимости, чтобы убедиться, что строка формата будет выровнена по 2-байтовой границе после FC_END.