Функция RtlEthernetStringToAddressA (ip2string.h)

Статья
03/14/2023

Функция RtlEthernetStringToAddress преобразует строковое представление MAC-адреса Ethernet в двоичный формат адреса Ethernet.

Синтаксис

NTSYSAPI NTSTATUS RtlEthernetStringToAddressA(
  [in]  PCSTR    S,
  [out] PCSTR    *Terminator,
  [out] DL_EUI48 *Addr
);

Параметры

[in] S

Указатель на буфер, содержащий NULLстроковое представление MAC-адреса Ethernet.

[out] Terminator

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

[out] Addr

Указатель, в котором должно храниться двоичное представление MAC-адреса Ethernet.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение STATUS_SUCCESS.

Если функция завершается ошибкой, возвращаемое значение является одним из следующих кодов ошибок.

Возвращаемый код	Описание
STATUS_INVALID_PARAMETER	Недопустимый параметр был передан функции. Эта ошибка возвращается, если строка, на которую указывает параметр S, не содержит правильное строковое представление MAC-адреса Ethernet. Этот код ошибки определен в файле заголовка Ntstatus.h.
Другие	Используйте FormatMessage, чтобы получить строку сообщения для возвращаемой ошибки.

Возвращаемый код

Описание

STATUS_INVALID_PARAMETER

Недопустимый параметр был передан функции. Эта ошибка возвращается, если строка, на которую указывает параметр S, не содержит правильное строковое представление MAC-адреса Ethernet.

Этот код ошибки определен в файле заголовка Ntstatus.h.

Другие

Используйте FormatMessage, чтобы получить строку сообщения для возвращаемой ошибки.

Замечания

Функция RtlEthernetStringToAddress используется для преобразования строкового представления адреса уровня канала данных Ethernet EUI-48 (также известного как MAC-адрес) в двоичный формат адреса Ethernet. Строка представляет числовый адрес Ethernet, выраженный в стандартной нотации "-'". Возвращаемое значение — это число, подходящее для использования в качестве адреса Ethernet. Все адреса Ethernet возвращаются в сетевом порядке (байты, упорядоченные слева направо).

Строка, указываемая параметром S, должна быть представлена в виде строки MAC-адреса Ethernet в нотации, отличной от DIX, стандартной нотации "-". Базовое строковое представление MAC-адреса Ethernet состоит из 6 пар шестнадцатеричных чисел, разделенных дефисами (например, F4-CE-46-2D-90-8C).

При успешном выполнении параметр указывает на символ, завершающий преобразованную строку. Это позволяет приложению передавать строку, содержащую адрес Ethernet, а также дополнительную информацию в функцию RtlEthernetStringToAddress, а затем проанализировать оставшиеся сведения.

RtlEthernetStringToAddress — это удобная функция, которая не требует загрузки библиотеки DLL сокетов Windows для доступа к функции, предоставленной в сокетах Windows для выполнения преобразования строк в адрес Ethernet.

При определении ЮНИКОДа или _UNICODE RtlEthernetStringToAddress определяется как RtlEthernetStringToAddressW, версия Юникода этой функции. Параметры S и терминатора определяются для типа данных PCWSTR.

Если не определены и ЮНИКОД, и _UNICODE, RtlEthernetStringToAddress определяется как RtlEthernetStringToAddressA, версия ANSI этой функции. Параметры S и терминатора определяются для типа данных PCSTR.

Тип данных DL_EUI48 определен в файле заголовка Mstcpip.h.

Заметка

Заголовок ip2string.h определяет RtlEthernetStringToAddress в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 7 [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2008 R2 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	ip2string.h (include Mstcpip.h, Ip2string.h)
библиотеки	ntdll.lib
DLL	ntdll.dll

См. также

RtlEthernetAddressToString

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