MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.h

   1 /**
   2   @file
   3
   4   EFI_REGULAR_EXPRESSION_PROTOCOL Header File.
   5
   6   Copyright (c) 2015, Hewlett Packard Enterprise Development, L.P.<BR>
   7
   8   This program and the accompanying materials are licensed and made available
   9   under the terms and conditions of the BSD License that accompanies this
  10   distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php.
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, WITHOUT
  14   WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15 **/
  16
  17 #include "Oniguruma/oniguruma.h"
  18
  19 #include <Uefi.h>
  20 #include <Protocol/RegularExpressionProtocol.h>
  21 #include <Library/UefiBootServicesTableLib.h>
  22 #include <Library/BaseMemoryLib.h>
  23 #include <Library/MemoryAllocationLib.h>
  24 #include <Library/DebugLib.h>
  25 #include <Library/BaseLib.h>
  26
  27 #define ARRAY_SIZE(Array) (sizeof(Array) / sizeof(*Array))
  28
  29 /**
  30   Checks if the input string matches to the regular expression pattern.
  31
  32   This          A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance.
  33                 Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section
  34                 XYZ.
  35
  36   String        A pointer to a NULL terminated string to match against the
  37                 regular expression string specified by Pattern.
  38
  39   Pattern       A pointer to a NULL terminated string that represents the
  40                 regular expression.
  41
  42   SyntaxType    A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the
  43                 regular expression syntax type to use. May be NULL in which
  44                 case the function will use its default regular expression
  45                 syntax type.
  46
  47   Result        On return, points to TRUE if String fully matches against
  48                 the regular expression Pattern using the regular expression
  49                 SyntaxType. Otherwise, points to FALSE.
  50
  51   Captures      A Pointer to an array of EFI_REGEX_CAPTURE objects to receive
  52                 the captured groups in the event of a match. The full
  53                 sub-string match is put in Captures[0], and the results of N
  54                 capturing groups are put in Captures[1:N]. If Captures is
  55                 NULL, then this function doesn't allocate the memory for the
  56                 array and does not build up the elements. It only returns the
  57                 number of matching patterns in CapturesCount. If Captures is
  58                 not NULL, this function returns a pointer to an array and
  59                 builds up the elements in the array. CapturesCount is also
  60                 updated to the number of matching patterns found. It is the
  61                 caller's responsibility to free the memory pool in Captures
  62                 and in each CapturePtr in the array elements.
  63
  64   CapturesCount On output, CapturesCount is the number of matching patterns
  65                 found in String. Zero means no matching patterns were found
  66                 in the string.
  67
  68   @retval EFI_SUCCESS            The regular expression string matching
  69                                  completed successfully.
  70   @retval EFI_UNSUPPORTED        The regular expression syntax specified by
  71                                  SyntaxType is not supported by this driver.
  72   @retval EFI_DEVICE_ERROR       The regular expression string matching
  73                                  failed due to a hardware or firmware error.
  74   @retval EFI_INVALID_PARAMETER  String, Pattern, Result, or CapturesCountis
  75                                  NULL.
  76
  77 **/
  78 EFI_STATUS
  79 EFIAPI
  80 RegularExpressionMatch (
  81   IN  EFI_REGULAR_EXPRESSION_PROTOCOL *This,
  82   IN  CHAR16                          *String,
  83   IN  CHAR16                          *Pattern,
  84   IN  EFI_REGEX_SYNTAX_TYPE           *SyntaxType, OPTIONAL
  85   OUT BOOLEAN                         *Result,
  86   OUT EFI_REGEX_CAPTURE               **Captures, OPTIONAL
  87   OUT UINTN                           *CapturesCount
  88   );
  89
  90 /**
  91   Returns information about the regular expression syntax types supported
  92   by the implementation.
  93
  94   This                     A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL
  95                            instance.
  96
  97   RegExSyntaxTypeListSize  On input, the size in bytes of RegExSyntaxTypeList.
  98                            On output with a return code of EFI_SUCCESS, the
  99                            size in bytes of the data returned in
 100                            RegExSyntaxTypeList. On output with a return code
 101                            of EFI_BUFFER_TOO_SMALL, the size of
 102                            RegExSyntaxTypeList required to obtain the list.
 103
 104   RegExSyntaxTypeList      A caller-allocated memory buffer filled by the
 105                            driver with one EFI_REGEX_SYNTAX_TYPE element
 106                            for each supported Regular expression syntax
 107                            type. The list must not change across multiple
 108                            calls to the same driver. The first syntax
 109                            type in the list is the default type for the
 110                            driver.
 111
 112   @retval EFI_SUCCESS            The regular expression syntax types list
 113                                  was returned successfully.
 114   @retval EFI_UNSUPPORTED        The service is not supported by this driver.
 115   @retval EFI_DEVICE_ERROR       The list of syntax types could not be
 116                                  retrieved due to a hardware or firmware error.
 117   @retval EFI_BUFFER_TOO_SMALL   The buffer RegExSyntaxTypeList is too small
 118                                  to hold the result.
 119   @retval EFI_INVALID_PARAMETER  RegExSyntaxTypeListSize is NULL
 120
 121 **/
 122 EFI_STATUS
 123 EFIAPI
 124 RegularExpressionGetInfo (
 125   IN     EFI_REGULAR_EXPRESSION_PROTOCOL *This,
 126   IN OUT UINTN                           *RegExSyntaxTypeListSize,
 127   OUT    EFI_REGEX_SYNTAX_TYPE           *RegExSyntaxTypeList
 128   );
 129
 130