MdePkg/Include/Protocol/Rest.h

   1 /** @file
   2   This file defines the EFI REST Protocol interface.
   3
   4   Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution. The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   @par Revision Reference:
  14   This Protocol is introduced in UEFI Specification 2.5
  15
  16 **/
  17
  18 #ifndef __EFI_REST_PROTOCOL_H__
  19 #define __EFI_REST_PROTOCOL_H__
  20
  21 #include <Protocol/Http.h>
  22
  23 #define EFI_REST_PROTOCOL_GUID \
  24   { \
  25     0x0db48a36, 0x4e54, 0xea9c, {0x9b, 0x09, 0x1e, 0xa5, 0xbe, 0x3a, 0x66, 0x0b } \
  26   }
  27
  28 typedef struct _EFI_REST_PROTOCOL EFI_REST_PROTOCOL;
  29
  30 /**
  31   Provides a simple HTTP-like interface to send and receive resources from a REST
  32   service.
  33
  34   The SendReceive() function sends an HTTP request to this REST service, and returns a
  35   response when the data is retrieved from the service. RequestMessage contains the HTTP
  36   request to the REST resource identified by RequestMessage.Request.Url. The
  37   ResponseMessage is the returned HTTP response for that request, including any HTTP
  38   status.
  39
  40   @param[in]  This                Pointer to EFI_REST_PROTOCOL instance for a particular
  41                                   REST service.
  42   @param[in]  RequestMessage      Pointer to the HTTP request data for this resource.
  43   @param[out] ResponseMessage     Pointer to the HTTP response data obtained for this
  44                                   requested.
  45
  46   @retval EFI_SUCCESS             Operation succeeded.
  47   @retval EFI_INVALID_PARAMETER   This, RequestMessage, or ResponseMessage are NULL.
  48   @retval EFI_DEVICE_ERROR        An unexpected system or network error occurred.
  49 **/
  50 typedef
  51 EFI_STATUS
  52 (EFIAPI *EFI_REST_SEND_RECEIVE) (
  53   IN  EFI_REST_PROTOCOL         *This,
  54   IN  EFI_HTTP_MESSAGE          *RequestMessage,
  55   OUT EFI_HTTP_MESSAGE          *ResponseMessage
  56   );
  57
  58 /**
  59   The GetServiceTime() function is an optional interface to obtain the current time from
  60   this REST service instance. If this REST service does not support retrieving the time,
  61   this function returns EFI_UNSUPPORTED.
  62
  63   @param[in]  This                Pointer to EFI_REST_PROTOCOL instance.
  64   @param[out] Time                A pointer to storage to receive a snapshot of the
  65                                   current time of the REST service.
  66
  67   @retval EFI_SUCCESS             Operation succeeded
  68   @retval EFI_INVALID_PARAMETER   This or Time are NULL.
  69   @retval EFI_UNSUPPORTED         The RESTful service does not support returning the
  70                                   time.
  71   @retval EFI_DEVICE_ERROR        An unexpected system or network error occurred.
  72 **/
  73 typedef
  74 EFI_STATUS
  75 (EFIAPI *EFI_REST_GET_TIME) (
  76   IN  EFI_REST_PROTOCOL         *This,
  77   OUT EFI_TIME                  *Time
  78   );
  79
  80 ///
  81 /// The EFI REST protocol is designed to be used by EFI drivers and applications to send
  82 /// and receive resources from a RESTful service. This protocol abstracts REST
  83 /// (Representational State Transfer) client functionality. This EFI protocol could be
  84 /// implemented to use an underlying EFI HTTP protocol, or it could rely on other
  85 /// interfaces that abstract HTTP access to the resources.
  86 ///
  87 struct _EFI_REST_PROTOCOL {
  88   EFI_REST_SEND_RECEIVE         SendReceive;
  89   EFI_REST_GET_TIME             GetServiceTime;
  90 };
  91
  92 extern EFI_GUID gEfiRestProtocolGuid;
  93
  94 #endif