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