RtlEthernetStringToAddress function

The RtlEthernetStringToAddress function converts a string representation of an Ethernet MAC address to a binary format of the Ethernet address.

Syntax

LONG NTAPI RtlEthernetStringToAddress(
  _In_  PCTSTR   S,
  _Out_ PCTSTR   *Terminator,
  _Out_ DL_EUI48 *Addr
);

Parameters

S [in]

A pointer to a buffer containing the NULL-terminated string representation of the Ethernet MAC address.

Terminator [out]

A parameter that receives a pointer to the character that terminated the converted string. This can be used by the caller to extract more information from the string.

Addr [out]

A pointer where the binary representation of the Ethernet MAC address is to be stored.

Return value

If the function succeeds, the return value is STATUS_SUCCESS.

If the function fails, the return value is one of the following error codes.

Remarks

The RtlEthernetStringToAddress function is used to convert a string representation of an Ethernet EUI-48 data-link layer address (also commonly known as a MAC address) to binary format of the Ethernet address. The string represents a numeric Ethernet address expressed in the non-DIX standard "-'' notation. The value returned is a number suitable for use as an Ethernet address. All Ethernet addresses are returned in network order (bytes ordered from left to right).

The string pointed to by the S parameter must be represented in the form for an Ethernet MAC address string in the non-DIX standard "-" notation. The basic string representation of an Ethernet MAC address consists of 6 pairs of hexadecimal numbers separated by dashes (F4-CE-46-2D-90-8C, for example).

On success, the Terminator parameter points to the character that terminated the string that was converted. This allows an application to pass a string that contains an Ethernet address plus additional information to the RtlEthernetStringToAddress function and then parse the remaining information.

RtlEthernetStringToAddress is a convenience function that does not require that the Windows Sockets DLL be loaded to access a function provided in Windows Sockets to perform string to Ethernet address conversion.

When either UNICODE or _UNICODE is defined, RtlEthernetStringToAddress is defined to RtlEthernetStringToAddressW, the Unicode version of this function. The S and Terminator parameters are defined to the PCWSTR data type.

When both UNICODE and _UNICODE are not defined, RtlEthernetStringToAddress is defined to RtlEthernetStringToAddressA, the ANSI version of this function. The S and Terminator parameters are defined to the PCSTR data type.

The DL_EUI48 data type is defined in the Mstcpip.h header file.

Requirements

See also

RtlEthernetAddressToString