Поделиться через

перечисление WS_READ_OPTION (webservices.h)

  • Статья

Указывает, является ли значение обязательным и каким образом должно быть выделено значение.

Синтаксис

typedef enum {
  WS_READ_REQUIRED_VALUE = 1,
  WS_READ_REQUIRED_POINTER = 2,
  WS_READ_OPTIONAL_POINTER = 3,
  WS_READ_NILLABLE_POINTER = 4,
  WS_READ_NILLABLE_VALUE = 5
} WS_READ_OPTION;

Константы

 
WS_READ_REQUIRED_VALUE
Значение: 1
Параметр указывает, что значение должно существовать в XML-содержимом.


Вызывающий объект должен указать хранилище для чтения типа верхнего уровня.


Размер хранилища, указанного вызывающим объектом, зависит от типа
десериализуются следующим образом:

  • Для примитивов (например , WS_INT32_TYPE) хранилище должно
    размер примитива. В этом случае кучу указывать не нужно.

  • Для структур (определяемых пользователем, использующих WS_STRUCT_TYPE;
    или предопределенные, например WS_STRING), хранилище должно быть
    точный размер структуры.
    Обратите внимание, что поля структуры, указывающие на другие данные, по-прежнему требуются
    будут выделены из WS_HEAP. Если для не существует полей
    конкретную структуру, то кучу указывать не нужно.




Типы указателей (WS_WSZ_TYPE и WS_XML_BUFFER_TYPE);
не может использоваться с WS_READ_REQUIRED_VALUE. WS_READ_REQUIRED_POINTER
Вместо этого следует использовать значение .


Если значение отсутствует в считываемом XML-коде,
будет возвращена ошибка WS_E_INVALID_FORMAT .
(См. раздел Возвращаемые значения веб-служб Windows.)
WS_READ_REQUIRED_POINTER
Значение: 2
Параметр указывает, что значение должно существовать в XML-содержимом.


Десериализованное значение всегда выделяется на WS_HEAP, независимо от его размера.
Возвращается указатель на десериализованное значение. При использовании этого параметра:
вызывающий объект должен передать адрес указателя и размер указателя.
независимо от десериализуемого типа.


Если значение отсутствует, будет возвращена ошибка.
Значение NULL никогда не возвращается при использовании этого параметра. Если
значение является необязательным, используйте WS_READ_OPTIONAL_POINTER.
WS_READ_OPTIONAL_POINTER
Значение: 3
Параметр указывает, что значение не обязательно существует в XML-содержимом.


Десериализованное значение всегда выделяется на WS_HEAP, независимо от его размера.
Возвращается указатель на десериализованное значение. При использовании этого параметра:
вызывающий объект должен передать адрес указателя и размер указателя.
независимо от десериализуемого типа.


Если значение отсутствует в считываемом XML-коде, функция будет
succeed и для значения будет возвращено значение NULL .


Приложение, использующее этот параметр, должно быть осторожным, чтобы проверка значение NULL, прежде чем получать доступ к значению.
Если значение NULL не ожидается, используйте WS_READ_REQUIRED_POINTER.
WS_READ_NILLABLE_POINTER
Значение: 4
Параметр указывает, что значение может быть равно нулю или отсутствовать в XML-содержимом.


Десериализованное значение всегда выделяется на WS_HEAP, независимо от его размера.
Возвращается указатель на десериализованное значение. При использовании этого параметра:
вызывающий объект должен передать адрес указателя и размер указателя.
независимо от десериализуемого типа.


Если элемент равен нулю или отсутствует в считываемом XML-коде, функция будет выполнена успешно и
будет возвращен указатель NULL .
Если элемент не равен нулю в считываемом XML-коде, значение возвращается обычным образом.


Приложение, использующее этот параметр, должно быть осторожным, чтобы проверка значение NULL, прежде чем получать доступ к значению.
Если значение NULL не ожидается, используйте WS_READ_REQUIRED_POINTER.


Этот параметр не поддерживается в сочетании с WS_TYPE_MAPPING в API
которые считывают XML, включая вызовы WsReadType и WsReadElement .
WS_READ_NILLABLE_VALUE
Значение: 5
Параметр указывает, что значение может быть равно нулю или отсутствовать в XML-содержимом.


Вызывающий объект должен указать хранилище для чтения типа верхнего уровня.


Если XML-элемент имеет значение nil или отсутствует, возвращается значение nil. Если XML-элемент имеет значение
если значение не равно нулю, то значение десериализуется нормально.


Этот параметр не поддерживается в сочетании с WS_TYPE_MAPPING в API
которые считывают XML, включая вызовы WsReadType и WsReadElement .


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

Комментарии

В каждом WS_READ_OPTION описывается, когда необходимо указать объект WS_HEAP . В зависимости от функции в этом случае может быть по-прежнему возможно передать параметр кучи NULL ; Дополнительные сведения о том, используется ли куча по умолчанию, если параметр кучи имеет значение NULL, см. в документации по конкретной функции.

Ниже приведены моменты, которые следует учитывать при десериализации значений в объект кучи (WS_HEAP):

  • Десериализованные значения остаются выделенными до освобождения кучи (WsFreeHeap) или сброса (WsResetHeap).
  • При каждом десериализации значения добавляются в кучу (вместо замены существующих значений).
  • Если во время десериализации функции возникают ошибки и функция завершается сбоем, память, выделенная из объекта кучи, до тех пор, пока ошибка не будет освобождена.
  • Размер кучи можно использовать для ограничения общего объема выделений, выполненных во время десериализации. Максимальный размер кучи можно определить следующим образом:
    • Определите максимальный размер (в байтах) каждого значения, которое будет выделено в куче во время десериализации. Помните, что размеры десериализованных структур данных могут отличаться в зависимости от платформы.
    • Каждый массив считается одним значением. Обратите внимание, что на фактический размер элемента в массиве может повлиять требуемое выравнивание элемента.
    • Округление максимального размера каждого значения до 16-байтовой границы.

Требования

Требование Значение
Минимальная версия клиента Windows 7 [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2008 R2 [классические приложения | Приложения UWP]
Верхняя часть webservices.h