MdePkg/Include/Protocol/RegularExpressionProtocol.h

   1 /** @file
   2   This section defines the Regular Expression Protocol. This protocol isused to match
   3   Unicode strings against Regular Expression patterns.
   4
   5 Copyright (c) 2015-2018, Intel Corporation. All rights reserved.<BR>
   6 This program and the accompanying materials are licensed and made available under
   7 the terms and conditions of the BSD License that accompanies this distribution.
   8 The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php.
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14   @par Revision Reference:
  15   This Protocol was introduced in UEFI Specification 2.5.
  16
  17 **/
  18
  19 #ifndef __REGULAR_EXPRESSION_PROTOCOL_H__
  20 #define __REGULAR_EXPRESSION_PROTOCOL_H__
  21
  22 #define EFI_REGULAR_EXPRESSION_PROTOCOL_GUID \
  23   { \
  24     0xB3F79D9A, 0x436C, 0xDC11, {0xB0, 0x52, 0xCD, 0x85, 0xDF, 0x52, 0x4C, 0xE6 } \
  25   }
  26
  27 #define EFI_REGEX_SYNTAX_TYPE_POSIX_EXTENDED_GUID \
  28   { \
  29     0x5F05B20F, 0x4A56, 0xC231, {0xFA, 0x0B, 0xA7, 0xB1, 0xF1, 0x10, 0x04, 0x1D } \
  30   }
  31
  32 #define EFI_REGEX_SYNTAX_TYPE_PERL_GUID \
  33   { \
  34     0x63E60A51, 0x497D, 0xD427, {0xC4, 0xA5, 0xB8, 0xAB, 0xDC, 0x3A, 0xAE, 0xB6 } \
  35   }
  36
  37 #define EFI_REGEX_SYNTAX_TYPE_ECMA_262_GUID \
  38   { \
  39     0x9A473A4A, 0x4CEB, 0xB95A, {0x41, 0x5E, 0x5B, 0xA0, 0xBC, 0x63, 0x9B, 0x2E } \
  40   }
  41
  42 typedef struct _EFI_REGULAR_EXPRESSION_PROTOCOL  EFI_REGULAR_EXPRESSION_PROTOCOL;
  43
  44
  45 typedef struct {
  46   CONST CHAR16 *CapturePtr; // Pointer to the start of the captured sub-expression
  47                             // within matched String.
  48
  49   UINTN        Length;      // Length of captured sub-expression.
  50 } EFI_REGEX_CAPTURE;
  51
  52 typedef EFI_GUID EFI_REGEX_SYNTAX_TYPE;
  53
  54 //
  55 // Protocol member functions
  56 //
  57 /**
  58   Returns information about the regular expression syntax types supported
  59   by the implementation.
  60
  61   This                     A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL
  62                            instance.
  63
  64   RegExSyntaxTypeListSize  On input, the size in bytes of RegExSyntaxTypeList.
  65                            On output with a return code of EFI_SUCCESS, the
  66                            size in bytes of the data returned in
  67                            RegExSyntaxTypeList. On output with a return code
  68                            of EFI_BUFFER_TOO_SMALL, the size of
  69                            RegExSyntaxTypeListrequired to obtain the list.
  70
  71   RegExSyntaxTypeList      A caller-allocated memory buffer filled by the
  72                            driver with one EFI_REGEX_SYNTAX_TYPEelement
  73                            for each supported Regular expression syntax
  74                            type. The list must not change across multiple
  75                            calls to the same driver. The first syntax
  76                            type in the list is the default type for the
  77                            driver.
  78
  79   @retval EFI_SUCCESS            The regular expression syntax types list
  80                                  was returned successfully.
  81   @retval EFI_UNSUPPORTED        The service is not supported by this driver.
  82   @retval EFI_DEVICE_ERROR       The list of syntax types could not be
  83                                  retrieved due to a hardware or firmware error.
  84   @retval EFI_BUFFER_TOO_SMALL   The buffer RegExSyntaxTypeList is too small
  85                                  to hold the result.
  86   @retval EFI_INVALID_PARAMETER  RegExSyntaxTypeListSize is NULL
  87
  88 **/
  89 typedef
  90 EFI_STATUS
  91 (EFIAPI *EFI_REGULAR_EXPRESSION_GET_INFO) (
  92   IN     EFI_REGULAR_EXPRESSION_PROTOCOL *This,
  93   IN OUT UINTN                           *RegExSyntaxTypeListSize,
  94   OUT    EFI_REGEX_SYNTAX_TYPE           *RegExSyntaxTypeList
  95   );
  96
  97 /**
  98   Checks if the input string matches to the regular expression pattern.
  99
 100   This          A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance.
 101                 Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section
 102                 XYZ.
 103
 104   String        A pointer to a NULL terminated string to match against the
 105                 regular expression string specified by Pattern.
 106
 107   Pattern       A pointer to a NULL terminated string that represents the
 108                 regular expression.
 109
 110   SyntaxType    A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the
 111                 regular expression syntax type to use. May be NULL in which
 112                 case the function will use its default regular expression
 113                 syntax type.
 114
 115   Result        On return, points to TRUE if String fully matches against
 116                 the regular expression Pattern using the regular expression
 117                 SyntaxType. Otherwise, points to FALSE.
 118
 119   Captures      A Pointer to an array of EFI_REGEX_CAPTURE objects to receive
 120                 the captured groups in the event of a match. The full
 121                 sub-string match is put in Captures[0], and the results of N
 122                 capturing groups are put in Captures[1:N]. If Captures is
 123                 NULL, then this function doesn't allocate the memory for the
 124                 array and does not build up the elements. It only returns the
 125                 number of matching patterns in CapturesCount. If Captures is
 126                 not NULL, this function returns a pointer to an array and
 127                 builds up the elements in the array. CapturesCount is also
 128                 updated to the number of matching patterns found. It is the
 129                 caller's responsibility to free the memory pool in Captures
 130                 and in each CapturePtr in the array elements.
 131
 132   CapturesCount On output, CapturesCount is the number of matching patterns
 133                 found in String. Zero means no matching patterns were found
 134                 in the string.
 135
 136   @retval EFI_SUCCESS            The regular expression string matching
 137                                  completed successfully.
 138   @retval EFI_UNSUPPORTED        The regular expression syntax specified by
 139                                  SyntaxTypeis not supported by this driver.
 140   @retval EFI_DEVICE_ERROR       The regular expression string matching
 141                                  failed due to a hardware or firmware error.
 142   @retval EFI_INVALID_PARAMETER  String, Pattern, Result, or CapturesCountis
 143                                  NULL.
 144
 145 **/
 146 typedef
 147 EFI_STATUS
 148 (EFIAPI *EFI_REGULAR_EXPRESSION_MATCH) (
 149   IN  EFI_REGULAR_EXPRESSION_PROTOCOL *This,
 150   IN  CHAR16                          *String,
 151   IN  CHAR16                          *Pattern,
 152   IN  EFI_REGEX_SYNTAX_TYPE           *SyntaxType, OPTIONAL
 153   OUT BOOLEAN                         *Result,
 154   OUT EFI_REGEX_CAPTURE               **Captures, OPTIONAL
 155   OUT UINTN                           *CapturesCount
 156   );
 157
 158 struct _EFI_REGULAR_EXPRESSION_PROTOCOL {
 159   EFI_REGULAR_EXPRESSION_MATCH     MatchString;
 160   EFI_REGULAR_EXPRESSION_GET_INFO  GetInfo;
 161 } ;
 162
 163 extern EFI_GUID gEfiRegularExpressionProtocolGuid;
 164
 165 //
 166 // For regular expression rules specified in the POSIX Extended Regular
 167 // Expression (ERE) Syntax:
 168 //
 169 extern EFI_GUID gEfiRegexSyntaxTypePosixExtendedGuid;
 170
 171 //
 172 // For regular expression rules specifiedin the ECMA 262 Specification
 173 //
 174 extern EFI_GUID gEfiRegexSyntaxTypeEcma262Guid;
 175
 176 //
 177 // For regular expression rules specified in the Perl standard:
 178 //
 179 extern EFI_GUID gEfiRegexSyntaxTypePerlGuid;
 180
 181 #endif