MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.h

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