From: "Yao, Jiewen" <jiewen.yao@intel.com>
To: "Ni, Ruiyu" <ruiyu.ni@intel.com>,
"edk2-devel@lists.01.org" <edk2-devel@lists.01.org>
Cc: "Gao, Liming" <liming.gao@intel.com>, "Fu, Siyuan" <siyuan.fu@intel.com>
Subject: Re: [PATCH 04/11] MdePkg/BaseLib: Add StrToGuid/StrHexToBytes/StrToIpv[4/6]Address
Date: Wed, 22 Feb 2017 08:14:39 +0000 [thread overview]
Message-ID: <74D8A39837DF1E4DA445A8C0B3885C503A8F3606@shsmsx102.ccr.corp.intel.com> (raw)
In-Reply-To: <734D49CCEBEEF84792F5B80ED585239D5B8AB296@SHSMSX104.ccr.corp.intel.com>
I think we should return better return status code.
If we return all cases with invalid parameter, the caller cannot know what is wrong.
Below is my thought:
I would return INVALID_PARAMETER if the something is wrong with the input string,
and return UNSUPPORTED if the format is not expected.
StrToIpv6Address()
+ @retval RETURN_INVALID_PARAMETER If String is NULL.
+ If Data is NULL.
+ If PcdMaximumUnicodeStringLength is not
+ zero, and String contains more than
+ PcdMaximumUnicodeStringLength Unicode
+ characters, not including the
+ Null-terminator.
+ @retval RETURN_UNSUPPORTED
+ If X contains more than four hexadecimal
+ digit characters.
+ If String contains "::" and number of X
+ is not less than 8.
+ If P starts with character that is not a
+ valid decimal digit character.
+ If the decimal number converted from P
+ exceeds 128.
StrToIpv4Address ()
+ @retval RETURN_INVALID_PARAMETER If String is NULL.
+ If Data is NULL.
+ If PcdMaximumUnicodeStringLength is not
+ zero, and String contains more than
+ PcdMaximumUnicodeStringLength Unicode
+ characters, not including the
+ Null-terminator.
+ @retval RETURN_UNSUPPORTED
+ If String is not in the correct format.
+ If any decimal number converted from D
+ exceeds 255.
+ If the decimal number converted from P
+ exceeds 32.
StrToGuid()
+ @retval RETURN_INVALID_PARAMETER If String is NULL.
+ If Data is NULL.
+ @retval RETURN_UNSUPPORTED
+ If String is not as the above format.
From: Ni, Ruiyu
Sent: Wednesday, February 22, 2017 3:58 PM
To: Yao, Jiewen <jiewen.yao@intel.com>; edk2-devel@lists.01.org
Cc: Gao, Liming <liming.gao@intel.com>; Fu, Siyuan <siyuan.fu@intel.com>
Subject: RE: [PATCH 04/11] MdePkg/BaseLib: Add StrToGuid/StrHexToBytes/StrToIpv[4/6]Address
Jiewen,
If we returns Unsupported for " 1.2.3.4".
What shall we return for " 1.2.3"?
If we need to return Invalid Parameter for " 1.2.3", the implementation has to check whether it's a valid IP address after spaces, or an invalid IP address.
Can you just return Invalid Parameter for all cases?
Thanks/Ray
> -----Original Message-----
> From: Yao, Jiewen
> Sent: Wednesday, February 22, 2017 2:02 PM
> To: Ni, Ruiyu <ruiyu.ni@intel.com<mailto:ruiyu.ni@intel.com>>; edk2-devel@lists.01.org<mailto:edk2-devel@lists.01.org>
> Cc: Gao, Liming <liming.gao@intel.com<mailto:liming.gao@intel.com>>; Fu, Siyuan <siyuan.fu@intel.com<mailto:siyuan.fu@intel.com>>
> Subject: RE: [PATCH 04/11] MdePkg/BaseLib: Add
> StrToGuid/StrHexToBytes/StrToIpv[4/6]Address
>
> Thanks.
>
> I suggest we clearly say: This function does not support the leading pad space ,
> which includes spaces or tab characters, before the first valid char.
>
> For example, " 1.2.3.4" is considered as invalid IPv4 address.
> And I suggest we return EFI_UNSUPPORTED.
>
> The comment is applied to add [Ascii]StrToGuid/IpV4/IpV6.
>
> Thank you
> Yao Jiewen
>
> > -----Original Message-----
> > From: Ni, Ruiyu
> > Sent: Wednesday, February 22, 2017 12:51 PM
> > To: edk2-devel@lists.01.org<mailto:edk2-devel@lists.01.org>
> > Cc: Gao, Liming <liming.gao@intel.com<mailto:liming.gao@intel.com>>; Yao, Jiewen
> > <jiewen.yao@intel.com<mailto:jiewen.yao@intel.com>>; Fu, Siyuan <siyuan.fu@intel.com<mailto:siyuan.fu@intel.com>>
> > Subject: [PATCH 04/11] MdePkg/BaseLib: Add
> > StrToGuid/StrHexToBytes/StrToIpv[4/6]Address
> >
> > The patch adds 4 APIs to convert Unicode string to GUID, bytes buffer,
> > IP v4 address and IP v6 address.
> >
> > Contributed-under: TianoCore Contribution Agreement 1.0
> > Signed-off-by: Ruiyu Ni <ruiyu.ni@intel.com<mailto:ruiyu.ni@intel.com>>
> > Cc: Liming Gao <liming.gao@intel.com<mailto:liming.gao@intel.com>>
> > Cc: Jiewen Yao <jiewen.yao@intel.com<mailto:jiewen.yao@intel.com>>
> > Cc: Siyuan Fu <siyuan.fu@intel.com<mailto:siyuan.fu@intel.com>>
> > ---
> > MdePkg/Include/Library/BaseLib.h | 241 ++++++++++++++
> > MdePkg/Library/BaseLib/SafeString.c | 623
> > ++++++++++++++++++++++++++++++++++++
> > 2 files changed, 864 insertions(+)
> >
> > diff --git a/MdePkg/Include/Library/BaseLib.h
> > b/MdePkg/Include/Library/BaseLib.h
> > index d71ccb7..8aac4c8 100644
> > --- a/MdePkg/Include/Library/BaseLib.h
> > +++ b/MdePkg/Include/Library/BaseLib.h
> > @@ -1536,6 +1536,247 @@ StrHexToUint64 (
> > IN CONST CHAR16 *String
> > );
> >
> > +/**
> > + Convert a Null-terminated Unicode string to IPv6 address and prefix length.
> > +
> > + This function outputs a value of type IPv6_ADDRESS and may output a
> > + value of type UINT8 by interpreting the contents of the Unicode
> > + string specified by String. The format of the input Unicode string String is as
> follows:
> > +
> > + X:X:X:X:X:X:X:X[/P]
> > +
> > + X contains one to four hexadecimal digit characters in the range
> > + [0-9], [a-f]
> > and
> > + [A-F]. X is converted to a value of type UINT16, whose low byte is
> > + stored in
> > low
> > + memory address and high byte is stored in high memory address. P
> > + contains
> > decimal
> > + digit characters in the range [0-9]. The running zero in the
> > + beginning of P will be ignored. /P is optional.
> > +
> > + When /P is not in the String, the function stops at the first
> > + character that is not a valid hexadecimal digit character after eight X's are
> converted.
> > +
> > + When /P is in the String, the function stops at the first character
> > + that is not a valid decimal digit character after P is converted.
> > +
> > + "::" can be used to compress one or more groups of X when X contains only
> 0.
> > + The "::" can only appear once in the String.
> > +
> > + If String is NULL, then ASSERT().
> > +
> > + If Address is NULL, then ASSERT().
> > +
> > + If String is not aligned in a 16-bit boundary, then ASSERT().
> > +
> > + If PcdMaximumUnicodeStringLength is not zero, and String contains
> > + more
> > than
> > + PcdMaximumUnicodeStringLength Unicode characters, not including the
> > + Null-terminator, then ASSERT().
> > +
> > + If EndPointer is not NULL and Address is translated from String, a
> > + pointer to the character that stopped the scan is stored at the
> > + location pointed to by EndPointer.
> > +
> > + @param String Pointer to a Null-terminated Unicode
> > string.
> > + @param EndPointer Pointer to character that stops scan.
> > + @param Address Pointer to the converted IPv6
> > address.
> > + @param PrefixLength Pointer to the converted IPv6 address
> > prefix
> > + length. MAX_UINT8 is returned when
> > /P is
> > + not in the String.
> > +
> > + @retval RETURN_SUCCESS Address is translated from String.
> > + @retval RETURN_INVALID_PARAMETER If String is NULL.
> > + If Data is NULL.
> > + If PcdMaximumUnicodeStringLength
> > + is
> > not
> > + zero, and String contains more than
> > + PcdMaximumUnicodeStringLength
> > Unicode
> > + characters, not including the
> > + Null-terminator.
> > + If X contains more than four
> > hexadecimal
> > + digit characters.
> > + If String contains "::" and number of X
> > + is not less than 8.
> > + If P starts with character that is not a
> > + valid decimal digit character.
> > + If the decimal number converted
> > + from
> > P
> > + exceeds 128.
> > +
> > +**/
> > +RETURN_STATUS
> > +EFIAPI
> > +StrToIpv6Address (
> > + IN CONST CHAR16 *String,
> > + OUT CHAR16 **EndPointer, OPTIONAL
> > + OUT IPv6_ADDRESS *Address,
> > + OUT UINT8 *PrefixLength OPTIONAL
> > + );
> > +
> > +/**
> > + Convert a Null-terminated Unicode string to IPv4 address and prefix length.
> > +
> > + This function outputs a value of type IPv4_ADDRESS and may output a
> > + value of type UINT8 by interpreting the contents of the Unicode
> > + string specified by String. The format of the input Unicode string String is as
> follows:
> > +
> > + D.D.D.D[/P]
> > +
> > + D and P are decimal digit characters in the range [0-9]. The
> > + running zero in the beginning of D and P will be ignored. /P is optional.
> > +
> > + When /P is not in the String, the function stops at the first
> > + character that is not a valid decimal digit character after four D's are
> converted.
> > +
> > + When /P is in the String, the function stops at the first character
> > + that is not a valid decimal digit character after P is converted.
> > +
> > + If String is NULL, then ASSERT().
> > +
> > + If Address is NULL, then ASSERT().
> > +
> > + If String is not aligned in a 16-bit boundary, then ASSERT().
> > +
> > + If PcdMaximumUnicodeStringLength is not zero, and String contains
> > + more
> > than
> > + PcdMaximumUnicodeStringLength Unicode characters, not including the
> > + Null-terminator, then ASSERT().
> > +
> > + If EndPointer is not NULL and Address is translated from String, a
> > + pointer to the character that stopped the scan is stored at the
> > + location pointed to by EndPointer.
> > +
> > + @param String Pointer to a Null-terminated Unicode
> > string.
> > + @param EndPointer Pointer to character that stops scan.
> > + @param Address Pointer to the converted IPv4
> > address.
> > + @param PrefixLength Pointer to the converted IPv4 address
> > prefix
> > + length. MAX_UINT8 is returned when
> > /P is
> > + not in the String.
> > +
> > + @retval RETURN_SUCCESS Address is translated from String.
> > + @retval RETURN_INVALID_PARAMETER If String is NULL.
> > + If Data is NULL.
> > + If PcdMaximumUnicodeStringLength
> > + is
> > not
> > + zero, and String contains more than
> > + PcdMaximumUnicodeStringLength
> > Unicode
> > + characters, not including the
> > + Null-terminator.
> > + If String is not in the correct format.
> > + If any decimal number converted
> > + from
> > D
> > + exceeds 255.
> > + If the decimal number converted
> > + from
> > P
> > + exceeds 32.
> > +
> > +**/
> > +RETURN_STATUS
> > +EFIAPI
> > +StrToIpv4Address (
> > + IN CONST CHAR16 *String,
> > + OUT CHAR16 **EndPointer, OPTIONAL
> > + OUT IPv4_ADDRESS *Address,
> > + OUT UINT8 *PrefixLength OPTIONAL
> > + );
> > +
> > +#define GUID_STRING_LENGTH 36
> > +
> > +/**
> > + Convert a Null-terminated Unicode GUID string to a value of type
> > + EFI_GUID.
> > +
> > + This function outputs a GUID value by interpreting the contents of
> > + the Unicode string specified by String. The format of the input
> > + Unicode string String consists of 36 characters, as follows:
> > +
> > + aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
> > +
> > + The pairs aa - pp are two characters in the range [0-9], [a-f] and
> > + [A-F], with each pair representing a single byte hexadecimal value.
> > +
> > + The mapping between String and the EFI_GUID structure is as follows:
> > + aa Data1[24:31]
> > + bb Data1[16:23]
> > + cc Data1[8:15]
> > + dd Data1[0:7]
> > + ee Data2[8:15]
> > + ff Data2[0:7]
> > + gg Data3[8:15]
> > + hh Data3[0:7]
> > + ii Data4[0:7]
> > + jj Data4[8:15]
> > + kk Data4[16:23]
> > + ll Data4[24:31]
> > + mm Data4[32:39]
> > + nn Data4[40:47]
> > + oo Data4[48:55]
> > + pp Data4[56:63]
> > +
> > + If String is NULL, then ASSERT().
> > + If Guid is NULL, then ASSERT().
> > + If String is not aligned in a 16-bit boundary, then ASSERT().
> > +
> > + @param String Pointer to a Null-terminated Unicode
> > string.
> > + @param Guid Pointer to the converted GUID.
> > +
> > + @retval RETURN_SUCCESS Guid is translated from String.
> > + @retval RETURN_INVALID_PARAMETER If String is NULL.
> > + If Data is NULL.
> > + If String is not as the above format.
> > +
> > +**/
> > +RETURN_STATUS
> > +EFIAPI
> > +StrToGuid (
> > + IN CONST CHAR16 *String,
> > + OUT GUID *Guid
> > + );
> > +
> > +/**
> > + Convert a Null-terminated Unicode hexadecimal string to a byte array.
> > +
> > + This function outputs a byte array by interpreting the contents of
> > + the Unicode string specified by String in hexadecimal format. The
> > + format of the input Unicode string String is:
> > +
> > + [XX]*
> > +
> > + X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
> > + The function decodes every two hexadecimal digit characters as one byte.
> > The
> > + decoding stops after Length of characters and outputs Buffer
> > + containing (Length / 2) bytes.
> > +
> > + If String is not aligned in a 16-bit boundary, then ASSERT().
> > +
> > + If String is NULL, then ASSERT().
> > +
> > + If Buffer is NULL, then ASSERT().
> > +
> > + If Length is not multiple of 2, then ASSERT().
> > +
> > + If PcdMaximumStringLength is not zero and Length is greater than
> > + PcdMaximumAsciiStringLength, then ASSERT().
> > +
> > + If MaxBufferSize is less than (Length / 2), then ASSERT().
> > +
> > + @param String Pointer to a Null-terminated Unicode
> > string.
> > + @param Length The number of Unicode characters to
> > decode.
> > + @param Buffer Pointer to the converted bytes array.
> > + @param MaxBufferSize The maximum size of Buffer.
> > +
> > + @retval RETURN_SUCCESS Buffer is translated from String.
> > + @retval RETURN_INVALID_PARAMETER If String is NULL.
> > + If Data is NULL.
> > + If Length is not multiple of 2.
> > + If PcdMaximumStringLength is not
> > zero,
> > + and Length is greater than
> > + PcdMaximumAsciiStringLength.
> > + If Length of characters from
> > + String
> > contain
> > + a character that is not valid
> > hexadecimal
> > + digit characters, or a Null-terminator.
> > + @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than
> > (Length / 2).
> > +**/
> > +RETURN_STATUS
> > +EFIAPI
> > +StrHexToBytes (
> > + IN CONST CHAR16 *String,
> > + IN UINTN Length,
> > + OUT UINT8 *Buffer,
> > + IN UINTN MaxBufferSize
> > + );
> > +
> > #ifndef DISABLE_NEW_DEPRECATED_INTERFACES
> >
> > /**
> > diff --git a/MdePkg/Library/BaseLib/SafeString.c
> > b/MdePkg/Library/BaseLib/SafeString.c
> > index 315059e..ede1c99 100644
> > --- a/MdePkg/Library/BaseLib/SafeString.c
> > +++ b/MdePkg/Library/BaseLib/SafeString.c
> > @@ -1074,6 +1074,629 @@ StrHexToUint64S ( }
> >
> > /**
> > + Convert a Null-terminated Unicode string to IPv6 address and prefix length.
> > +
> > + This function outputs a value of type IPv6_ADDRESS and may output a
> > + value of type UINT8 by interpreting the contents of the Unicode
> > + string specified by String. The format of the input Unicode string String is as
> follows:
> > +
> > + X:X:X:X:X:X:X:X[/P]
> > +
> > + X contains one to four hexadecimal digit characters in the range
> > + [0-9], [a-f]
> > and
> > + [A-F]. X is converted to a value of type UINT16, whose low byte is
> > + stored in
> > low
> > + memory address and high byte is stored in high memory address. P
> > + contains
> > decimal
> > + digit characters in the range [0-9]. The running zero in the
> > + beginning of P will be ignored. /P is optional.
> > +
> > + When /P is not in the String, the function stops at the first
> > + character that is not a valid hexadecimal digit character after eight X's are
> converted.
> > +
> > + When /P is in the String, the function stops at the first character
> > + that is not a valid decimal digit character after P is converted.
> > +
> > + "::" can be used to compress one or more groups of X when X contains only
> 0.
> > + The "::" can only appear once in the String.
> > +
> > + If String is NULL, then ASSERT().
> > +
> > + If Address is NULL, then ASSERT().
> > +
> > + If String is not aligned in a 16-bit boundary, then ASSERT().
> > +
> > + If PcdMaximumUnicodeStringLength is not zero, and String contains
> > + more
> > than
> > + PcdMaximumUnicodeStringLength Unicode characters, not including the
> > + Null-terminator, then ASSERT().
> > +
> > + If EndPointer is not NULL and Address is translated from String, a
> > + pointer to the character that stopped the scan is stored at the
> > + location pointed to by EndPointer.
> > +
> > + @param String Pointer to a Null-terminated Unicode
> > string.
> > + @param EndPointer Pointer to character that stops scan.
> > + @param Address Pointer to the converted IPv6
> > address.
> > + @param PrefixLength Pointer to the converted IPv6 address
> > prefix
> > + length. MAX_UINT8 is returned when
> > /P is
> > + not in the String.
> > +
> > + @retval RETURN_SUCCESS Address is translated from String.
> > + @retval RETURN_INVALID_PARAMETER If String is NULL.
> > + If Data is NULL.
> > + If PcdMaximumUnicodeStringLength
> > + is
> > not
> > + zero, and String contains more than
> > + PcdMaximumUnicodeStringLength
> > Unicode
> > + characters, not including the
> > + Null-terminator.
> > + If X contains more than four
> > hexadecimal
> > + digit characters.
> > + If String contains "::" and number of X
> > + is not less than 8.
> > + If P starts with character that is not a
> > + valid decimal digit character.
> > + If the decimal number converted
> > + from
> > P
> > + exceeds 128.
> > +
> > +**/
> > +RETURN_STATUS
> > +EFIAPI
> > +StrToIpv6Address (
> > + IN CONST CHAR16 *String,
> > + OUT CHAR16 **EndPointer, OPTIONAL
> > + OUT IPv6_ADDRESS *Address,
> > + OUT UINT8 *PrefixLength OPTIONAL
> > + )
> > +{
> > + RETURN_STATUS Status;
> > + UINTN AddressIndex;
> > + UINTN Uintn;
> > + IPv6_ADDRESS LocalAddress;
> > + UINT8 LocalPrefixLength;
> > + CONST CHAR16 *Pointer;
> > + CHAR16 *End;
> > + UINTN CompressStart;
> > + BOOLEAN ExpectPrefix;
> > +
> > + LocalPrefixLength = MAX_UINT8;
> > + CompressStart = ARRAY_SIZE (Address->Addr);
> > + ExpectPrefix = FALSE;
> > +
> > + ASSERT (((UINTN) String & BIT0) == 0);
> > +
> > + //
> > + // 1. None of String or Guid shall be a null pointer.
> > + //
> > + SAFE_STRING_CONSTRAINT_CHECK ((String != NULL),
> > RETURN_INVALID_PARAMETER);
> > + SAFE_STRING_CONSTRAINT_CHECK ((Address != NULL),
> > RETURN_INVALID_PARAMETER);
> > +
> > + for (Pointer = String, AddressIndex = 0; AddressIndex < ARRAY_SIZE
> > (Address->Addr) + 1;) {
> > + if (!InternalIsHexaDecimalDigitCharacter (*Pointer)) {
> > + if (*Pointer != L':') {
> > + //
> > + // ":" or "/" should be followed by digit characters.
> > + //
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > +
> > + //
> > + // Meet second ":" after previous ":" or "/"
> > + // or meet first ":" in the beginning of String.
> > + //
> > + if (ExpectPrefix) {
> > + //
> > + // ":" shall not be after "/"
> > + //
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > +
> > + if (CompressStart != ARRAY_SIZE (Address->Addr) || AddressIndex
> > + ==
> > ARRAY_SIZE (Address->Addr)) {
> > + //
> > + // "::" can only appear once.
> > + // "::" can only appear when address is not full length.
> > + //
> > + return RETURN_INVALID_PARAMETER;
> > + } else {
> > + //
> > + // Remember the start of zero compressing.
> > + //
> > + CompressStart = AddressIndex;
> > + Pointer++;
> > +
> > + if (CompressStart == 0) {
> > + if (*Pointer != L':') {
> > + //
> > + // Single ":" shall not be in the beginning of String.
> > + //
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + Pointer++;
> > + }
> > + }
> > + }
> > +
> > + if (!InternalIsHexaDecimalDigitCharacter (*Pointer)) {
> > + if (*Pointer == L'/') {
> > + //
> > + // Might be optional "/P" after "::".
> > + //
> > + if (CompressStart != AddressIndex) {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + } else {
> > + break;
> > + }
> > + } else {
> > + if (!ExpectPrefix) {
> > + //
> > + // Get X.
> > + //
> > + Status = StrHexToUintnS (Pointer, &End, &Uintn);
> > + if (RETURN_ERROR (Status) || End - Pointer > 4) {
> > + //
> > + // Number of hexadecimal digit characters is no more than 4.
> > + //
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + Pointer = End;
> > + //
> > + // Uintn won't exceed MAX_UINT16 if number of hexadecimal
> > + digit
> > characters is no more than 4.
> > + //
> > + LocalAddress.Addr[AddressIndex] = (UINT8) ((UINT16) Uintn >> 8);
> > + LocalAddress.Addr[AddressIndex + 1] = (UINT8) Uintn;
> > + AddressIndex += 2;
> > + } else {
> > + //
> > + // Get P, then exit the loop.
> > + //
> > + Status = StrDecimalToUintnS (Pointer, &End, &Uintn);
> > + if (RETURN_ERROR (Status) || End == Pointer || Uintn > 128) {
> > + //
> > + // Prefix length should not exceed 128.
> > + //
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + LocalPrefixLength = (UINT8) Uintn;
> > + Pointer = End;
> > + break;
> > + }
> > + }
> > +
> > + //
> > + // Skip ':' or "/"
> > + //
> > + if (*Pointer == L'/') {
> > + ExpectPrefix = TRUE;
> > + } else if (*Pointer == L':') {
> > + if (AddressIndex == ARRAY_SIZE (Address->Addr)) {
> > + //
> > + // Meet additional ":" after all 8 16-bit address
> > + //
> > + break;
> > + }
> > + } else {
> > + //
> > + // Meet other character that is not "/" or ":" after all 8 16-bit address
> > + //
> > + break;
> > + }
> > + Pointer++;
> > + }
> > +
> > + if ((AddressIndex == ARRAY_SIZE (Address->Addr) && CompressStart !=
> > ARRAY_SIZE (Address->Addr)) ||
> > + (AddressIndex != ARRAY_SIZE (Address->Addr) && CompressStart ==
> > ARRAY_SIZE (Address->Addr))
> > + ) {
> > + //
> > + // Full length of address shall not have compressing zeros.
> > + // Non-full length of address shall have compressing zeros.
> > + //
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + CopyMem (&Address->Addr[0], &LocalAddress.Addr[0], CompressStart);
> > + ZeroMem (&Address->Addr[CompressStart], ARRAY_SIZE (Address->Addr) -
> > AddressIndex);
> > + CopyMem (
> > + &Address->Addr[CompressStart + ARRAY_SIZE (Address->Addr) -
> > AddressIndex],
> > + &LocalAddress.Addr[CompressStart],
> > + AddressIndex - CompressStart
> > + );
> > +
> > + if (PrefixLength != NULL) {
> > + *PrefixLength = LocalPrefixLength; } if (EndPointer != NULL) {
> > + *EndPointer = (CHAR16 *) Pointer; }
> > +
> > + return RETURN_SUCCESS;
> > +}
> > +
> > +/**
> > + Convert a Null-terminated Unicode string to IPv4 address and prefix length.
> > +
> > + This function outputs a value of type IPv4_ADDRESS and may output a
> > + value of type UINT8 by interpreting the contents of the Unicode
> > + string specified by String. The format of the input Unicode string String is as
> follows:
> > +
> > + D.D.D.D[/P]
> > +
> > + D and P are decimal digit characters in the range [0-9]. The
> > + running zero in the beginning of D and P will be ignored. /P is optional.
> > +
> > + When /P is not in the String, the function stops at the first
> > + character that is not a valid decimal digit character after four D's are
> converted.
> > +
> > + When /P is in the String, the function stops at the first character
> > + that is not a valid decimal digit character after P is converted.
> > +
> > + If String is NULL, then ASSERT().
> > +
> > + If Address is NULL, then ASSERT().
> > +
> > + If String is not aligned in a 16-bit boundary, then ASSERT().
> > +
> > + If PcdMaximumUnicodeStringLength is not zero, and String contains
> > + more
> > than
> > + PcdMaximumUnicodeStringLength Unicode characters, not including the
> > + Null-terminator, then ASSERT().
> > +
> > + If EndPointer is not NULL and Address is translated from String, a
> > + pointer to the character that stopped the scan is stored at the
> > + location pointed to by EndPointer.
> > +
> > + @param String Pointer to a Null-terminated Unicode
> > string.
> > + @param EndPointer Pointer to character that stops scan.
> > + @param Address Pointer to the converted IPv4
> > address.
> > + @param PrefixLength Pointer to the converted IPv4 address
> > prefix
> > + length. MAX_UINT8 is returned when
> > /P is
> > + not in the String.
> > +
> > + @retval RETURN_SUCCESS Address is translated from String.
> > + @retval RETURN_INVALID_PARAMETER If String is NULL.
> > + If Data is NULL.
> > + If PcdMaximumUnicodeStringLength
> > + is
> > not
> > + zero, and String contains more than
> > + PcdMaximumUnicodeStringLength
> > Unicode
> > + characters, not including the
> > + Null-terminator.
> > + If String is not in the correct format.
> > + If any decimal number converted
> > + from
> > D
> > + exceeds 255.
> > + If the decimal number converted
> > + from
> > P
> > + exceeds 32.
> > +
> > +**/
> > +RETURN_STATUS
> > +EFIAPI
> > +StrToIpv4Address (
> > + IN CONST CHAR16 *String,
> > + OUT CHAR16 **EndPointer, OPTIONAL
> > + OUT IPv4_ADDRESS *Address,
> > + OUT UINT8 *PrefixLength OPTIONAL
> > + )
> > +{
> > + RETURN_STATUS Status;
> > + UINTN AddressIndex;
> > + UINTN Uintn;
> > + IPv4_ADDRESS LocalAddress;
> > + UINT8 LocalPrefixLength;
> > + CHAR16 *Pointer;
> > +
> > + LocalPrefixLength = MAX_UINT8;
> > +
> > + ASSERT (((UINTN) String & BIT0) == 0);
> > +
> > + //
> > + // 1. None of String or Guid shall be a null pointer.
> > + //
> > + SAFE_STRING_CONSTRAINT_CHECK ((String != NULL),
> > RETURN_INVALID_PARAMETER);
> > + SAFE_STRING_CONSTRAINT_CHECK ((Address != NULL),
> > RETURN_INVALID_PARAMETER);
> > +
> > + for (Pointer = (CHAR16 *) String, AddressIndex = 0; AddressIndex <
> > ARRAY_SIZE (Address->Addr) + 1;) {
> > + if (!InternalIsDecimalDigitCharacter (*Pointer)) {
> > + //
> > + // D or P contains invalid characters.
> > + //
> > + break;
> > + }
> > +
> > + //
> > + // Get D or P.
> > + //
> > + Status = StrDecimalToUintnS ((CONST CHAR16 *) Pointer, &Pointer,
> > &Uintn);
> > + if (RETURN_ERROR (Status)) {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + if (AddressIndex == ARRAY_SIZE (Address->Addr)) {
> > + //
> > + // It's P.
> > + //
> > + if (Uintn > 32) {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + LocalPrefixLength = (UINT8) Uintn;
> > + } else {
> > + //
> > + // It's D.
> > + //
> > + if (Uintn > MAX_UINT8) {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + LocalAddress.Addr[AddressIndex] = (UINT8) Uintn;
> > + AddressIndex++;
> > + }
> > +
> > + //
> > + // Check the '.' or '/', depending on the AddressIndex.
> > + //
> > + if (AddressIndex == ARRAY_SIZE (Address->Addr)) {
> > + if (*Pointer == L'/') {
> > + //
> > + // '/P' is in the String.
> > + // Skip "/" and get P in next loop.
> > + //
> > + Pointer++;
> > + } else {
> > + //
> > + // '/P' is not in the String.
> > + //
> > + break;
> > + }
> > + } else if (AddressIndex < ARRAY_SIZE (Address->Addr)) {
> > + if (*Pointer == L'.') {
> > + //
> > + // D should be followed by '.'
> > + //
> > + Pointer++;
> > + } else {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + }
> > + }
> > +
> > + if (AddressIndex < ARRAY_SIZE (Address->Addr)) {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > +
> > + CopyMem (Address, &LocalAddress, sizeof (*Address)); if
> > + (PrefixLength != NULL) {
> > + *PrefixLength = LocalPrefixLength; } if (EndPointer != NULL) {
> > + *EndPointer = Pointer;
> > + }
> > +
> > + return RETURN_SUCCESS;
> > +}
> > +
> > +/**
> > + Convert a Null-terminated Unicode GUID string to a value of type
> > + EFI_GUID.
> > +
> > + This function outputs a GUID value by interpreting the contents of
> > + the Unicode string specified by String. The format of the input
> > + Unicode string String consists of 36 characters, as follows:
> > +
> > + aabbccdd-eeff-gghh-iijj-kkllmmnnoopp
> > +
> > + The pairs aa - pp are two characters in the range [0-9], [a-f] and
> > + [A-F], with each pair representing a single byte hexadecimal value.
> > +
> > + The mapping between String and the EFI_GUID structure is as follows:
> > + aa Data1[24:31]
> > + bb Data1[16:23]
> > + cc Data1[8:15]
> > + dd Data1[0:7]
> > + ee Data2[8:15]
> > + ff Data2[0:7]
> > + gg Data3[8:15]
> > + hh Data3[0:7]
> > + ii Data4[0:7]
> > + jj Data4[8:15]
> > + kk Data4[16:23]
> > + ll Data4[24:31]
> > + mm Data4[32:39]
> > + nn Data4[40:47]
> > + oo Data4[48:55]
> > + pp Data4[56:63]
> > +
> > + If String is NULL, then ASSERT().
> > + If Guid is NULL, then ASSERT().
> > + If String is not aligned in a 16-bit boundary, then ASSERT().
> > +
> > + @param String Pointer to a Null-terminated Unicode
> > string.
> > + @param Guid Pointer to the converted GUID.
> > +
> > + @retval RETURN_SUCCESS Guid is translated from String.
> > + @retval RETURN_INVALID_PARAMETER If String is NULL.
> > + If Data is NULL.
> > + If String is not as the above format.
> > +
> > +**/
> > +RETURN_STATUS
> > +EFIAPI
> > +StrToGuid (
> > + IN CONST CHAR16 *String,
> > + OUT GUID *Guid
> > + )
> > +{
> > + RETURN_STATUS Status;
> > + GUID LocalGuid;
> > +
> > + ASSERT (((UINTN) String & BIT0) == 0);
> > +
> > + //
> > + // 1. None of String or Guid shall be a null pointer.
> > + //
> > + SAFE_STRING_CONSTRAINT_CHECK ((String != NULL),
> > RETURN_INVALID_PARAMETER);
> > + SAFE_STRING_CONSTRAINT_CHECK ((Guid != NULL),
> > RETURN_INVALID_PARAMETER);
> > +
> > + //
> > + // Get aabbccdd in big-endian.
> > + //
> > + Status = StrHexToBytes (String, 2 * sizeof (LocalGuid.Data1),
> > + (UINT8 *)
> > &LocalGuid.Data1, sizeof (LocalGuid.Data1));
> > + if (RETURN_ERROR (Status) || String[2 * sizeof (LocalGuid.Data1)] != L'-') {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + //
> > + // Convert big-endian to little-endian.
> > + //
> > + LocalGuid.Data1 = SwapBytes32 (LocalGuid.Data1); String += 2 *
> > + sizeof (LocalGuid.Data1) + 1;
> > +
> > + //
> > + // Get eeff in big-endian.
> > + //
> > + Status = StrHexToBytes (String, 2 * sizeof (LocalGuid.Data2),
> > + (UINT8 *)
> > &LocalGuid.Data2, sizeof (LocalGuid.Data2));
> > + if (RETURN_ERROR (Status) || String[2 * sizeof (LocalGuid.Data2)] != L'-') {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + //
> > + // Convert big-endian to little-endian.
> > + //
> > + LocalGuid.Data2 = SwapBytes16 (LocalGuid.Data2); String += 2 *
> > + sizeof (LocalGuid.Data2) + 1;
> > +
> > + //
> > + // Get gghh in big-endian.
> > + //
> > + Status = StrHexToBytes (String, 2 * sizeof (LocalGuid.Data3),
> > + (UINT8 *)
> > &LocalGuid.Data3, sizeof (LocalGuid.Data3));
> > + if (RETURN_ERROR (Status) || String[2 * sizeof (LocalGuid.Data3)] != L'-') {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + //
> > + // Convert big-endian to little-endian.
> > + //
> > + LocalGuid.Data3 = SwapBytes16 (LocalGuid.Data3); String += 2 *
> > + sizeof (LocalGuid.Data3) + 1;
> > +
> > + //
> > + // Get iijj.
> > + //
> > + Status = StrHexToBytes (String, 2 * 2, &LocalGuid.Data4[0], 2); if
> > + (RETURN_ERROR (Status) || String[2 * 2] != L'-') {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > + String += 2 * 2 + 1;
> > +
> > + //
> > + // Get kkllmmnnoopp.
> > + //
> > + Status = StrHexToBytes (String, 2 * 6, &LocalGuid.Data4[2], 6); if
> > + (RETURN_ERROR (Status)) {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > +
> > + CopyGuid (Guid, &LocalGuid);
> > + return RETURN_SUCCESS;
> > +}
> > +
> > +/**
> > + Convert a Null-terminated Unicode hexadecimal string to a byte array.
> > +
> > + This function outputs a byte array by interpreting the contents of
> > + the Unicode string specified by String in hexadecimal format. The
> > + format of the input Unicode string String is:
> > +
> > + [XX]*
> > +
> > + X is a hexadecimal digit character in the range [0-9], [a-f] and [A-F].
> > + The function decodes every two hexadecimal digit characters as one byte.
> > The
> > + decoding stops after Length of characters and outputs Buffer
> > + containing (Length / 2) bytes.
> > +
> > + If String is not aligned in a 16-bit boundary, then ASSERT().
> > +
> > + If String is NULL, then ASSERT().
> > +
> > + If Buffer is NULL, then ASSERT().
> > +
> > + If Length is not multiple of 2, then ASSERT().
> > +
> > + If PcdMaximumStringLength is not zero and Length is greater than
> > + PcdMaximumAsciiStringLength, then ASSERT().
> > +
> > + If MaxBufferSize is less than (Length / 2), then ASSERT().
> > +
> > + @param String Pointer to a Null-terminated Unicode
> > string.
> > + @param Length The number of Unicode characters to
> > decode.
> > + @param Buffer Pointer to the converted bytes array.
> > + @param MaxBufferSize The maximum size of Buffer.
> > +
> > + @retval RETURN_SUCCESS Buffer is translated from String.
> > + @retval RETURN_INVALID_PARAMETER If String is NULL.
> > + If Data is NULL.
> > + If Length is not multiple of 2.
> > + If PcdMaximumStringLength is not
> > zero,
> > + and Length is greater than
> > + PcdMaximumAsciiStringLength.
> > + If Length of characters from
> > + String
> > contain
> > + a character that is not valid
> > hexadecimal
> > + digit characters, or a Null-terminator.
> > + @retval RETURN_BUFFER_TOO_SMALL If MaxBufferSize is less than
> > (Length / 2).
> > +**/
> > +RETURN_STATUS
> > +EFIAPI
> > +StrHexToBytes (
> > + IN CONST CHAR16 *String,
> > + IN UINTN Length,
> > + OUT UINT8 *Buffer,
> > + IN UINTN MaxBufferSize
> > + )
> > +{
> > + UINTN Index;
> > +
> > + ASSERT (((UINTN) String & BIT0) == 0);
> > +
> > + //
> > + // 1. None of String or Buffer shall be a null pointer.
> > + //
> > + SAFE_STRING_CONSTRAINT_CHECK ((String != NULL),
> > RETURN_INVALID_PARAMETER);
> > + SAFE_STRING_CONSTRAINT_CHECK ((Buffer != NULL),
> > RETURN_INVALID_PARAMETER);
> > +
> > + //
> > + // 2. Length shall not be greater than RSIZE_MAX.
> > + //
> > + if (RSIZE_MAX != 0) {
> > + SAFE_STRING_CONSTRAINT_CHECK ((Length <= RSIZE_MAX),
> > RETURN_INVALID_PARAMETER);
> > + }
> > +
> > + //
> > + // 3. Length shall not be odd.
> > + //
> > + SAFE_STRING_CONSTRAINT_CHECK (((Length & BIT0) == 0),
> > RETURN_INVALID_PARAMETER);
> > +
> > + //
> > + // 4. MaxBufferSize shall equal to or greater than Length / 2.
> > + //
> > + SAFE_STRING_CONSTRAINT_CHECK ((MaxBufferSize >= Length / 2),
> > RETURN_BUFFER_TOO_SMALL);
> > +
> > + //
> > + // 5. String shall not contains invalid hexadecimal digits.
> > + //
> > + for (Index = 0; Index < Length; Index++) {
> > + if (!InternalIsHexaDecimalDigitCharacter (String[Index])) {
> > + break;
> > + }
> > + }
> > + if (Index != Length) {
> > + return RETURN_INVALID_PARAMETER;
> > + }
> > +
> > + //
> > + // Convert the hex string to bytes.
> > + //
> > + for(Index = 0; Index < Length; Index++) {
> > +
> > + //
> > + // For even characters, write the upper nibble for each buffer byte,
> > + // and for even characters, the lower nibble.
> > + //
> > + if ((Index & BIT0) == 0) {
> > + Buffer[Index / 2] = (UINT8) InternalHexCharToUintn
> > + (String[Index]) <<
> > 4;
> > + } else {
> > + Buffer[Index / 2] |= (UINT8) InternalHexCharToUintn (String[Index]);
> > + }
> > + }
> > + return RETURN_SUCCESS;
> > +}
> > +
> > +/**
> > Returns the length of a Null-terminated Ascii string.
> >
> > This function is similar as strlen_s defined in C11.
> > --
> > 2.9.0.windows.1
next prev parent reply other threads:[~2017-02-22 8:14 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-02-22 4:50 [PATCH 00/11] Add StrToGuid/HexToBytes/Ipv4/Ipv6 in BaseLib Ruiyu Ni
2017-02-22 4:50 ` [PATCH 01/11] MdePkg: Define IPv4_ADDRESS and IPv6_ADDRESS in Base.h Ruiyu Ni
2017-02-22 4:50 ` [PATCH 02/11] MdePkg/UefiDevicePathLib: Rename StrToGuid to avoid link failure Ruiyu Ni
2017-02-22 4:50 ` [PATCH 03/11] SignedCapsulePkg/IniParsing: " Ruiyu Ni
2017-02-22 4:50 ` [PATCH 04/11] MdePkg/BaseLib: Add StrToGuid/StrHexToBytes/StrToIpv[4/6]Address Ruiyu Ni
2017-02-22 6:02 ` Yao, Jiewen
2017-02-22 7:58 ` Ni, Ruiyu
2017-02-22 8:14 ` Yao, Jiewen [this message]
2017-02-22 4:50 ` [PATCH 05/11] MdePkg/BaseLib: Add AsciiStrToGuid/HexToBytes/ToIpv[4/6]Address Ruiyu Ni
2017-02-22 4:50 ` [PATCH 06/11] MdePkg/UefiDevicePathLib: Use BaseLib string conversion services Ruiyu Ni
2017-02-22 4:50 ` [PATCH 07/11] MdeModulePkg/CapsuleApp: Use StrToGuid in BaseLib Ruiyu Ni
2017-02-22 4:50 ` [PATCH 08/11] SecurityPkg/SecureBootConfigDxe: " Ruiyu Ni
2017-02-22 4:50 ` [PATCH 09/11] ShellPkg/Debug1CommandLib: Use StrToGuid/StrHexToBytes " Ruiyu Ni
2017-02-22 4:50 ` [PATCH 10/11] SignedCapsulePkg/IniParsingLib: Use AsciiStrToGuid " Ruiyu Ni
2017-02-22 5:28 ` Yao, Jiewen
2017-02-22 7:40 ` Ni, Ruiyu
2017-02-22 4:50 ` [PATCH 11/11] MdeModulePkg/NetLib: Use StrToIpv4/6Address " Ruiyu Ni
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-list from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=74D8A39837DF1E4DA445A8C0B3885C503A8F3606@shsmsx102.ccr.corp.intel.com \
--to=devel@edk2.groups.io \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox