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