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