RedfishPkg/RedfishRestExDxe/RedfishRestExProtocol.c

   1 /** @file
   2   Implementation of Redfish EFI_REST_EX_PROTOCOL interfaces.
   3
   4    Copyright (c) 2019, Intel Corporation. All rights reserved.<BR>
   5   (C) Copyright 2020 Hewlett Packard Enterprise Development LP<BR>
   6   Copyright (c) 2023, American Megatrends International LLC.
   7   Copyright (c) 2023, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
   8
   9   SPDX-License-Identifier: BSD-2-Clause-Patent
  10
  11 **/
  12 #include <Uefi.h>
  13 #include "RedfishRestExInternal.h"
  14
  15 EFI_REST_EX_PROTOCOL  mRedfishRestExProtocol = {
  16   RedfishRestExSendReceive,
  17   RedfishRestExGetServiceTime,
  18   RedfishRestExGetService,
  19   RedfishRestExGetModeData,
  20   RedfishRestExConfigure,
  21   RedfishRestExAyncSendReceive,
  22   RedfishRestExEventService
  23 };
  24
  25 /**
  26   Provides a simple HTTP-like interface to send and receive resources from a REST service.
  27
  28   The SendReceive() function sends an HTTP request to this REST service, and returns a
  29   response when the data is retrieved from the service. RequestMessage contains the HTTP
  30   request to the REST resource identified by RequestMessage.Request.Url. The
  31   ResponseMessage is the returned HTTP response for that request, including any HTTP
  32   status.
  33
  34   @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a particular
  35                                   REST service.
  36   @param[in]  RequestMessage      Pointer to the HTTP request data for this resource
  37   @param[out] ResponseMessage     Pointer to the HTTP response data obtained for this requested.
  38
  39   @retval EFI_SUCCESS             operation succeeded.
  40   @retval EFI_INVALID_PARAMETER   This, RequestMessage, or ResponseMessage are NULL.
  41   @retval EFI_DEVICE_ERROR        An unexpected system or network error occurred.
  42   @retval EFI_ACCESS_DENIED       HTTP method is not allowed on this URL.
  43   @retval EFI_BAD_BUFFER_SIZE     The payload is to large to be handled on server side.
  44   @retval EFI_UNSUPPORTED         Unsupported HTTP response.
  45
  46 **/
  47 EFI_STATUS
  48 EFIAPI
  49 RedfishRestExSendReceive (
  50   IN      EFI_REST_EX_PROTOCOL  *This,
  51   IN      EFI_HTTP_MESSAGE      *RequestMessage,
  52   OUT     EFI_HTTP_MESSAGE      *ResponseMessage
  53   )
  54 {
  55   EFI_STATUS                      Status;
  56   RESTEX_INSTANCE                 *Instance;
  57   HTTP_IO_RESPONSE_DATA           *ResponseData;
  58   UINTN                           TotalReceivedSize;
  59   UINTN                           Index;
  60   LIST_ENTRY                      *ChunkListLink;
  61   HTTP_IO_CHUNKS                  *ThisChunk;
  62   BOOLEAN                         CopyChunkData;
  63   BOOLEAN                         MediaPresent;
  64   EFI_HTTP_HEADER                 *PreservedRequestHeaders;
  65   BOOLEAN                         ItsWrite;
  66   BOOLEAN                         IsGetChunkedTransfer;
  67   HTTP_IO_SEND_CHUNK_PROCESS      SendChunkProcess;
  68   HTTP_IO_SEND_NON_CHUNK_PROCESS  SendNonChunkProcess;
  69   EFI_HTTP_MESSAGE                ChunkTransferRequestMessage;
  70
  71   Status                  = EFI_SUCCESS;
  72   ResponseData            = NULL;
  73   IsGetChunkedTransfer    = FALSE;
  74   SendChunkProcess        = HttpIoSendChunkNone;
  75   SendNonChunkProcess     = HttpIoSendNonChunkNone;
  76   ItsWrite                = FALSE;
  77   PreservedRequestHeaders = NULL;
  78
  79   //
  80   // Validate the parameters
  81   //
  82   if ((This == NULL) || (RequestMessage == NULL) || (ResponseMessage == NULL)) {
  83     return EFI_INVALID_PARAMETER;
  84   }
  85
  86   Instance = RESTEX_INSTANCE_FROM_THIS (This);
  87
  88   //
  89   // Check Media Status.
  90   //
  91   MediaPresent = TRUE;
  92   NetLibDetectMedia (Instance->Service->ControllerHandle, &MediaPresent);
  93   if (!MediaPresent) {
  94     DEBUG ((DEBUG_REDFISH_NETWORK, "RedfishRestExSendReceive(): No MediaPresent.\n"));
  95     return EFI_NO_MEDIA;
  96   }
  97
  98   DEBUG ((DEBUG_REDFISH_NETWORK, "\nRedfishRestExSendReceive():\n"));
  99   DEBUG ((DEBUG_REDFISH_NETWORK, "*** Perform HTTP Request Method - %d, URL: %s\n", RequestMessage->Data.Request->Method, RequestMessage->Data.Request->Url));
 100
 101   if (FixedPcdGetBool (PcdRedfishRestExChunkRequestMode)) {
 102     //
 103     // Add header "Expect" to server, only for URL write.
 104     //
 105     Status = RedfishHttpAddExpectation (This, RequestMessage, &PreservedRequestHeaders, &ItsWrite);
 106     if (EFI_ERROR (Status)) {
 107       return Status;
 108     }
 109
 110     if (ItsWrite == TRUE) {
 111       if (RequestMessage->BodyLength > HTTP_IO_MAX_SEND_PAYLOAD) {
 112         //
 113         // Send chunked transfer.
 114         //
 115         SendChunkProcess++;
 116         CopyMem ((VOID *)&ChunkTransferRequestMessage, (VOID *)RequestMessage, sizeof (EFI_HTTP_MESSAGE));
 117       } else {
 118         SendNonChunkProcess++;
 119       }
 120     }
 121   }
 122
 123 ReSendRequest:;
 124
 125   if (FixedPcdGetBool (PcdRedfishRestExChunkRequestMode)) {
 126     //
 127     // Send the chunked request to REST service.
 128     //
 129     if (ItsWrite == TRUE) {
 130       //
 131       // This is write to URI
 132       //
 133       if (SendChunkProcess > HttpIoSendChunkNone) {
 134         //
 135         // This is chunk transfer for writing large payload.
 136         // Send request header first and then handle the
 137         // following request message body using chunk transfer.
 138         //
 139         do {
 140           Status = HttpIoSendChunkedTransfer (
 141                      &(Instance->HttpIo),
 142                      &SendChunkProcess,
 143                      &ChunkTransferRequestMessage
 144                      );
 145           if (EFI_ERROR (Status)) {
 146             goto ON_EXIT;
 147           }
 148         } while (SendChunkProcess == HttpIoSendChunkContent || SendChunkProcess == HttpIoSendChunkEndChunk);
 149       } else {
 150         //
 151         // This is the non-chunk transfer, send request header first and then
 152         // handle the following request message body using chunk transfer.
 153         //
 154         Status = HttpIoSendRequest (
 155                    &(Instance->HttpIo),
 156                    (SendNonChunkProcess == HttpIoSendNonChunkContent) ? NULL : RequestMessage->Data.Request,
 157                    (SendNonChunkProcess == HttpIoSendNonChunkContent) ? 0 : RequestMessage->HeaderCount,
 158                    (SendNonChunkProcess == HttpIoSendNonChunkContent) ? NULL : RequestMessage->Headers,
 159                    (SendNonChunkProcess == HttpIoSendNonChunkHeaderZeroContent) ? 0 : RequestMessage->BodyLength,
 160                    (SendNonChunkProcess == HttpIoSendNonChunkHeaderZeroContent) ? NULL : RequestMessage->Body
 161                    );
 162       }
 163     } else {
 164       //
 165       // This is read from URI.
 166       //
 167       Status = HttpIoSendRequest (
 168                  &(Instance->HttpIo),
 169                  RequestMessage->Data.Request,
 170                  RequestMessage->HeaderCount,
 171                  RequestMessage->Headers,
 172                  RequestMessage->BodyLength,
 173                  RequestMessage->Body
 174                  );
 175     }
 176   } else {
 177     //
 178     // This is normal request to URI.
 179     //
 180     Status = HttpIoSendRequest (
 181                &(Instance->HttpIo),
 182                RequestMessage->Data.Request,
 183                RequestMessage->HeaderCount,
 184                RequestMessage->Headers,
 185                RequestMessage->BodyLength,
 186                RequestMessage->Body
 187                );
 188   }
 189
 190   if (EFI_ERROR (Status)) {
 191     goto ON_EXIT;
 192   }
 193
 194   //
 195   // ResponseMessage->Data.Response is to indicate whether to receive the HTTP header or not.
 196   // ResponseMessage->BodyLength/ResponseMessage->Body are to indicate whether to receive the response body or not.
 197   // Clean the previous buffers and all of them will be allocated later according to the actual situation.
 198   //
 199   if (ResponseMessage->Data.Response != NULL) {
 200     FreePool (ResponseMessage->Data.Response);
 201     ResponseMessage->Data.Response = NULL;
 202   }
 203
 204   ResponseMessage->BodyLength = 0;
 205   if (ResponseMessage->Body != NULL) {
 206     FreePool (ResponseMessage->Body);
 207     ResponseMessage->Body = NULL;
 208   }
 209
 210   //
 211   // Use zero BodyLength to only receive the response headers.
 212   //
 213   ResponseData = AllocateZeroPool (sizeof (HTTP_IO_RESPONSE_DATA));
 214   if (ResponseData == NULL) {
 215     Status = EFI_OUT_OF_RESOURCES;
 216     goto ON_EXIT;
 217   }
 218
 219   DEBUG ((DEBUG_REDFISH_NETWORK, "Receiving HTTP response and headers...\n"));
 220   Status = RedfishCheckHttpReceiveStatus (
 221              Instance,
 222              HttpIoRecvResponse (
 223                &(Instance->HttpIo),
 224                TRUE,
 225                ResponseData
 226                )
 227              );
 228   if (Status == EFI_NOT_READY) {
 229     goto ReSendRequest;
 230   } else if (Status == EFI_DEVICE_ERROR) {
 231     goto ON_EXIT;
 232   }
 233
 234   //
 235   // Restore the headers if it ever changed in RedfishHttpAddExpectation().
 236   //
 237   if (FixedPcdGetBool (PcdRedfishRestExAddingExpect) && (RequestMessage->Headers != PreservedRequestHeaders)) {
 238     FreePool (RequestMessage->Headers);
 239     RequestMessage->Headers = PreservedRequestHeaders; // Restore headers before we adding "Expect".
 240     RequestMessage->HeaderCount--;                     // Minus one header count for "Expect".
 241   }
 242
 243   DEBUG ((DEBUG_REDFISH_NETWORK, "HTTP Response StatusCode - %d:", ResponseData->Response.StatusCode));
 244   if (ResponseData->Response.StatusCode == HTTP_STATUS_200_OK) {
 245     DEBUG ((DEBUG_REDFISH_NETWORK, "HTTP_STATUS_200_OK\n"));
 246
 247     if (FixedPcdGetBool (PcdRedfishRestExChunkRequestMode) && (SendChunkProcess == HttpIoSendChunkHeaderZeroContent)) {
 248       DEBUG ((DEBUG_REDFISH_NETWORK, "This is chunk transfer, start to send all chunks - %d.", ResponseData->Response.StatusCode));
 249       SendChunkProcess++;
 250       goto ReSendRequest;
 251     }
 252   } else if (ResponseData->Response.StatusCode == HTTP_STATUS_204_NO_CONTENT) {
 253     DEBUG ((DEBUG_INFO, "HTTP_STATUS_204_NO_CONTENT\n"));
 254
 255     if (FixedPcdGetBool (PcdRedfishRestExChunkRequestMode) && (SendChunkProcess == HttpIoSendChunkHeaderZeroContent)) {
 256       DEBUG ((DEBUG_INFO, "This is chunk transfer, start to send all chunks - %d.", ResponseData->Response.StatusCode));
 257       SendChunkProcess++;
 258       goto ReSendRequest;
 259     }
 260   } else if (ResponseData->Response.StatusCode == HTTP_STATUS_201_CREATED) {
 261     DEBUG ((DEBUG_INFO, "HTTP_STATUS_201_CREATED\n"));
 262   } else if (ResponseData->Response.StatusCode == HTTP_STATUS_202_ACCEPTED) {
 263     DEBUG ((DEBUG_INFO, "HTTP_STATUS_202_ACCEPTED\n"));
 264   } else if (ResponseData->Response.StatusCode == HTTP_STATUS_413_REQUEST_ENTITY_TOO_LARGE) {
 265     DEBUG ((DEBUG_REDFISH_NETWORK, "HTTP_STATUS_413_REQUEST_ENTITY_TOO_LARGE\n"));
 266
 267     Status = EFI_BAD_BUFFER_SIZE;
 268     goto ON_EXIT;
 269   } else if (ResponseData->Response.StatusCode == HTTP_STATUS_405_METHOD_NOT_ALLOWED) {
 270     DEBUG ((DEBUG_ERROR, "HTTP_STATUS_405_METHOD_NOT_ALLOWED\n"));
 271
 272     Status = EFI_ACCESS_DENIED;
 273     goto ON_EXIT;
 274   } else if (ResponseData->Response.StatusCode == HTTP_STATUS_400_BAD_REQUEST) {
 275     DEBUG ((DEBUG_REDFISH_NETWORK, "HTTP_STATUS_400_BAD_REQUEST\n"));
 276     if (FixedPcdGetBool (PcdRedfishRestExChunkRequestMode) && (SendChunkProcess == HttpIoSendChunkHeaderZeroContent)) {
 277       DEBUG ((DEBUG_REDFISH_NETWORK, "Bad request may caused by zero length chunk. Try to send all chunks...\n"));
 278       SendChunkProcess++;
 279       goto ReSendRequest;
 280     }
 281   } else if (ResponseData->Response.StatusCode == HTTP_STATUS_100_CONTINUE) {
 282     DEBUG ((DEBUG_REDFISH_NETWORK, "HTTP_STATUS_100_CONTINUE\n"));
 283     if (FixedPcdGetBool (PcdRedfishRestExChunkRequestMode) && (SendChunkProcess == HttpIoSendChunkHeaderZeroContent)) {
 284       //
 285       // We get HTTP_STATUS_100_CONTINUE to send the body using chunk transfer.
 286       //
 287       DEBUG ((DEBUG_REDFISH_NETWORK, "HTTP_STATUS_100_CONTINUE for chunk transfer...\n"));
 288       SendChunkProcess++;
 289       goto ReSendRequest;
 290     }
 291
 292     if (FixedPcdGetBool (PcdRedfishRestExChunkRequestMode) && (SendNonChunkProcess == HttpIoSendNonChunkHeaderZeroContent)) {
 293       DEBUG ((DEBUG_REDFISH_NETWORK, "HTTP_STATUS_100_CONTINUE for non chunk transfer...\n"));
 294       SendNonChunkProcess++;
 295       goto ReSendRequest;
 296     }
 297
 298     //
 299     // It's the REST protocol's responsibility to handle the interim HTTP response (e.g. 100 Continue Informational),
 300     // and return the final response content to the caller.
 301     //
 302     if ((ResponseData->Headers != NULL) && (ResponseData->HeaderCount != 0)) {
 303       FreePool (ResponseData->Headers);
 304     }
 305
 306     ZeroMem (ResponseData, sizeof (HTTP_IO_RESPONSE_DATA));
 307     Status = HttpIoRecvResponse (
 308                &(Instance->HttpIo),
 309                TRUE,
 310                ResponseData
 311                );
 312     if (EFI_ERROR (Status)) {
 313       goto ON_EXIT;
 314     }
 315   } else {
 316     DEBUG ((DEBUG_ERROR, "This HTTP Status is not handled!\n"));
 317     DumpHttpStatusCode (DEBUG_REDFISH_NETWORK, ResponseData->Response.StatusCode);
 318     Status = EFI_UNSUPPORTED;
 319     goto ON_EXIT;
 320   }
 321
 322   //
 323   // Ready to return the StatusCode, Header info and BodyLength.
 324   //
 325   ResponseMessage->Data.Response = AllocateZeroPool (sizeof (EFI_HTTP_RESPONSE_DATA));
 326   if (ResponseMessage->Data.Response == NULL) {
 327     Status = EFI_OUT_OF_RESOURCES;
 328     goto ON_EXIT;
 329   }
 330
 331   ResponseMessage->Data.Response->StatusCode = ResponseData->Response.StatusCode;
 332   ResponseMessage->HeaderCount               = ResponseData->HeaderCount;
 333   ResponseMessage->Headers                   = ResponseData->Headers;
 334
 335   //
 336   // Get response message body.
 337   //
 338   if (ResponseMessage->HeaderCount > 0) {
 339     Status = HttpIoGetContentLength (ResponseMessage->HeaderCount, ResponseMessage->Headers, &ResponseMessage->BodyLength);
 340     if (EFI_ERROR (Status) && (Status != EFI_NOT_FOUND)) {
 341       goto ON_EXIT;
 342     }
 343
 344     if (Status == EFI_NOT_FOUND) {
 345       ASSERT (ResponseMessage->BodyLength == 0);
 346     }
 347
 348     if (ResponseMessage->BodyLength == 0) {
 349       //
 350       // Check if Chunked Transfer Coding.
 351       //
 352       Status = HttpIoGetChunkedTransferContent (
 353                  &(Instance->HttpIo),
 354                  ResponseMessage->HeaderCount,
 355                  ResponseMessage->Headers,
 356                  &ChunkListLink,
 357                  &ResponseMessage->BodyLength
 358                  );
 359       if (EFI_ERROR (Status) && (Status != EFI_NOT_FOUND)) {
 360         goto ON_EXIT;
 361       }
 362
 363       if ((Status == EFI_SUCCESS) &&
 364           (ChunkListLink != NULL) &&
 365           !IsListEmpty (ChunkListLink) &&
 366           (ResponseMessage->BodyLength != 0))
 367       {
 368         IsGetChunkedTransfer = TRUE;
 369         //
 370         // Copy data to Message body.
 371         //
 372         CopyChunkData         = TRUE;
 373         ResponseMessage->Body = AllocateZeroPool (ResponseMessage->BodyLength);
 374         if (ResponseMessage->Body == NULL) {
 375           Status        = EFI_OUT_OF_RESOURCES;
 376           CopyChunkData = FALSE;
 377         }
 378
 379         Index = 0;
 380         while (!IsListEmpty (ChunkListLink)) {
 381           ThisChunk = (HTTP_IO_CHUNKS *)GetFirstNode (ChunkListLink);
 382           if (CopyChunkData) {
 383             CopyMem (((UINT8 *)ResponseMessage->Body + Index), (UINT8 *)ThisChunk->Data, ThisChunk->Length);
 384             Index += ThisChunk->Length;
 385           }
 386
 387           RemoveEntryList (&ThisChunk->NextChunk);
 388           FreePool ((VOID *)ThisChunk->Data);
 389           FreePool ((VOID *)ThisChunk);
 390         }
 391
 392         FreePool ((VOID *)ChunkListLink);
 393       }
 394     }
 395
 396     Status = EFI_SUCCESS;
 397   }
 398
 399   //
 400   // Ready to return the Body from REST service if have any.
 401   //
 402   if ((ResponseMessage->BodyLength > 0) && !IsGetChunkedTransfer) {
 403     ResponseData->HeaderCount = 0;
 404     ResponseData->Headers     = NULL;
 405
 406     ResponseMessage->Body = AllocateZeroPool (ResponseMessage->BodyLength);
 407     if (ResponseMessage->Body == NULL) {
 408       Status = EFI_OUT_OF_RESOURCES;
 409       goto ON_EXIT;
 410     }
 411
 412     //
 413     // Only receive the Body.
 414     //
 415     TotalReceivedSize = 0;
 416     while (TotalReceivedSize < ResponseMessage->BodyLength) {
 417       ResponseData->BodyLength = ResponseMessage->BodyLength - TotalReceivedSize;
 418       ResponseData->Body       = (CHAR8 *)ResponseMessage->Body + TotalReceivedSize;
 419       Status                   = HttpIoRecvResponse (
 420                                    &(Instance->HttpIo),
 421                                    FALSE,
 422                                    ResponseData
 423                                    );
 424       if (EFI_ERROR (Status)) {
 425         goto ON_EXIT;
 426       }
 427
 428       TotalReceivedSize += ResponseData->BodyLength;
 429     }
 430
 431     DEBUG ((DEBUG_REDFISH_NETWORK, "Total of length of Response :%d\n", TotalReceivedSize));
 432   }
 433
 434   DEBUG ((DEBUG_REDFISH_NETWORK, "RedfishRestExSendReceive()- EFI_STATUS: %r\n", Status));
 435
 436 ON_EXIT:
 437
 438   if (ResponseData != NULL) {
 439     FreePool (ResponseData);
 440   }
 441
 442   if (EFI_ERROR (Status)) {
 443     if (ResponseMessage->Data.Response != NULL) {
 444       FreePool (ResponseMessage->Data.Response);
 445       ResponseMessage->Data.Response = NULL;
 446     }
 447
 448     if (ResponseMessage->Body != NULL) {
 449       FreePool (ResponseMessage->Body);
 450       ResponseMessage->Body = NULL;
 451     }
 452   }
 453
 454   return Status;
 455 }
 456
 457 /**
 458   Obtain the current time from this REST service instance.
 459
 460   The GetServiceTime() function is an optional interface to obtain the current time from
 461   this REST service instance. If this REST service does not support to retrieve the time,
 462   this function returns EFI_UNSUPPORTED. This function must returns EFI_UNSUPPORTED if
 463   EFI_REST_EX_SERVICE_TYPE returned in EFI_REST_EX_SERVICE_INFO from GetService() is
 464   EFI_REST_EX_SERVICE_UNSPECIFIC.
 465
 466   @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a particular
 467                                   REST service.
 468   @param[out] Time                A pointer to storage to receive a snapshot of the current time of
 469                                   the REST service.
 470
 471   @retval EFI_SUCCESS             operation succeeded.
 472   @retval EFI_INVALID_PARAMETER   This or Time are NULL.
 473   @retval EFI_UNSUPPORTED         The RESTful service does not support returning the time.
 474   @retval EFI_DEVICE_ERROR        An unexpected system or network error occurred.
 475   @retval EFI_NOT_READY           The configuration of this instance is not set yet. Configure() must
 476                                   be executed and returns successfully prior to invoke this function.
 477
 478 **/
 479 EFI_STATUS
 480 EFIAPI
 481 RedfishRestExGetServiceTime (
 482   IN      EFI_REST_EX_PROTOCOL  *This,
 483   OUT     EFI_TIME              *Time
 484   )
 485 {
 486   return EFI_UNSUPPORTED;
 487 }
 488
 489 /**
 490   This function returns the information of REST service provided by this EFI REST EX driver instance.
 491
 492   The information such as the type of REST service and the access mode of REST EX driver instance
 493   (In-band or Out-of-band) are described in EFI_REST_EX_SERVICE_INFO structure. For the vendor-specific
 494   REST service, vendor-specific REST service information is returned in VendorSpecifcData.
 495   REST EX driver designer is well know what REST service this REST EX driver instance intends to
 496   communicate with. The designer also well know this driver instance is used to talk to BMC through
 497   specific platform mechanism or talk to REST server through UEFI HTTP protocol. REST EX driver is
 498   responsible to fill up the correct information in EFI_REST_EX_SERVICE_INFO. EFI_REST_EX_SERVICE_INFO
 499   is referred by EFI REST clients to pickup the proper EFI REST EX driver instance to get and set resource.
 500   GetService() is a basic and mandatory function which must be able to use even Configure() is not invoked
 501   in previously.
 502
 503   @param[in]  This                Pointer to EFI_REST_EX_PROTOCOL instance for a particular
 504                                   REST service.
 505   @param[out] RestExServiceInfo   Pointer to receive a pointer to EFI_REST_EX_SERVICE_INFO structure. The
 506                                   format of EFI_REST_EX_SERVICE_INFO is version controlled for the future
 507                                   extension. The version of EFI_REST_EX_SERVICE_INFO structure is returned
 508                                   in the header within this structure. EFI REST client refers to the correct
 509                                   format of structure according to the version number. The pointer to
 510                                   EFI_REST_EX_SERVICE_INFO is a memory block allocated by EFI REST EX driver
 511                                   instance. That is caller's responsibility to free this memory when this
 512                                   structure is no longer needed. Refer to Related Definitions below for the
 513                                   definitions of EFI_REST_EX_SERVICE_INFO structure.
 514
 515   @retval EFI_SUCCESS             EFI_REST_EX_SERVICE_INFO is returned in RestExServiceInfo. This function
 516                                   is not supported in this REST EX Protocol driver instance.
 517   @retval EFI_UNSUPPORTED         This function is not supported in this REST EX Protocol driver instance.
 518
 519 **/
 520 EFI_STATUS
 521 EFIAPI
 522 RedfishRestExGetService (
 523   IN   EFI_REST_EX_PROTOCOL      *This,
 524   OUT  EFI_REST_EX_SERVICE_INFO  **RestExServiceInfo
 525   )
 526 {
 527   EFI_TPL                   OldTpl;
 528   RESTEX_INSTANCE           *Instance;
 529   EFI_REST_EX_SERVICE_INFO  *ServiceInfo;
 530
 531   ServiceInfo = NULL;
 532
 533   if ((This == NULL) || (RestExServiceInfo == NULL)) {
 534     return EFI_INVALID_PARAMETER;
 535   }
 536
 537   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 538
 539   Instance = RESTEX_INSTANCE_FROM_THIS (This);
 540
 541   ServiceInfo = AllocateZeroPool (sizeof (EFI_REST_EX_SERVICE_INFO));
 542   if (ServiceInfo == NULL) {
 543     return EFI_OUT_OF_RESOURCES;
 544   }
 545
 546   CopyMem (ServiceInfo, &(Instance->Service->RestExServiceInfo), sizeof (EFI_REST_EX_SERVICE_INFO));
 547
 548   *RestExServiceInfo = ServiceInfo;
 549
 550   gBS->RestoreTPL (OldTpl);
 551
 552   return EFI_SUCCESS;
 553 }
 554
 555 /**
 556   This function returns operational configuration of current EFI REST EX child instance.
 557
 558   This function returns the current configuration of EFI REST EX child instance. The format of
 559   operational configuration depends on the implementation of EFI REST EX driver instance. For
 560   example, HTTP-aware EFI REST EX driver instance uses EFI HTTP protocol as the undying protocol
 561   to communicate with REST service. In this case, the type of configuration is
 562   EFI_REST_EX_CONFIG_TYPE_HTTP returned from GetService(). EFI_HTTP_CONFIG_DATA is used as EFI REST
 563   EX configuration format and returned to EFI REST client. User has to type cast RestExConfigData
 564   to EFI_HTTP_CONFIG_DATA. For those non HTTP-aware REST EX driver instances, the type of configuration
 565   is EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC returned from GetService(). In this case, the format of
 566   returning data could be non industrial. Instead, the format of configuration data is system/platform
 567   specific definition such as BMC mechanism used in EFI REST EX driver instance. EFI REST client and
 568   EFI REST EX driver instance have to refer to the specific system /platform spec which is out of UEFI scope.
 569
 570   @param[in]  This                This is the EFI_REST_EX_PROTOCOL instance.
 571   @param[out] RestExConfigData    Pointer to receive a pointer to EFI_REST_EX_CONFIG_DATA.
 572                                   The memory allocated for configuration data should be freed
 573                                   by caller. See Related Definitions for the details.
 574
 575   @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is returned in successfully.
 576   @retval EFI_UNSUPPORTED         This function is not supported in this REST EX Protocol driver instance.
 577   @retval EFI_NOT_READY           The configuration of this instance is not set yet. Configure() must be
 578                                   executed and returns successfully prior to invoke this function.
 579
 580 **/
 581 EFI_STATUS
 582 EFIAPI
 583 RedfishRestExGetModeData (
 584   IN  EFI_REST_EX_PROTOCOL     *This,
 585   OUT EFI_REST_EX_CONFIG_DATA  *RestExConfigData
 586   )
 587 {
 588   return EFI_UNSUPPORTED;
 589 }
 590
 591 /**
 592   This function is used to configure EFI REST EX child instance.
 593
 594   This function is used to configure the setting of underlying protocol of REST EX child
 595   instance. The type of configuration is according to the implementation of EFI REST EX
 596   driver instance. For example, HTTP-aware EFI REST EX driver instance uses EFI HTTP protocol
 597   as the undying protocol to communicate with REST service. The type of configuration is
 598   EFI_REST_EX_CONFIG_TYPE_HTTP and RestExConfigData is the same format with EFI_HTTP_CONFIG_DATA.
 599   Akin to HTTP configuration, REST EX child instance can be configure to use different HTTP
 600   local access point for the data transmission. Multiple REST clients may use different
 601   configuration of HTTP to distinguish themselves, such as to use the different TCP port.
 602   For those non HTTP-aware REST EX driver instance, the type of configuration is
 603   EFI_REST_EX_CONFIG_TYPE_UNSPECIFIC. RestExConfigData refers to the non industrial standard.
 604   Instead, the format of configuration data is system/platform specific definition such as BMC.
 605   In this case, EFI REST client and EFI REST EX driver instance have to refer to the specific
 606   system/platform spec which is out of the UEFI scope. Besides GetService()function, no other
 607   EFI REST EX functions can be executed by this instance until Configure()is executed and returns
 608   successfully. All other functions must returns EFI_NOT_READY if this instance is not configured
 609   yet. Set RestExConfigData to NULL means to put EFI REST EX child instance into the unconfigured
 610   state.
 611
 612   @param[in]  This                This is the EFI_REST_EX_PROTOCOL instance.
 613   @param[in]  RestExConfigData    Pointer to EFI_REST_EX_CONFIG_DATA. See Related Definitions in
 614                                   GetModeData() protocol interface.
 615
 616   @retval EFI_SUCCESS             EFI_REST_EX_CONFIG_DATA is set in successfully.
 617   @retval EFI_DEVICE_ERROR        Configuration for this REST EX child instance is failed with the given
 618                                   EFI_REST_EX_CONFIG_DATA.
 619   @retval EFI_UNSUPPORTED         This function is not supported in this REST EX Protocol driver instance.
 620
 621 **/
 622 EFI_STATUS
 623 EFIAPI
 624 RedfishRestExConfigure (
 625   IN  EFI_REST_EX_PROTOCOL     *This,
 626   IN  EFI_REST_EX_CONFIG_DATA  RestExConfigData
 627   )
 628 {
 629   EFI_STATUS       Status;
 630   EFI_TPL          OldTpl;
 631   RESTEX_INSTANCE  *Instance;
 632
 633   EFI_HTTP_CONFIG_DATA  *HttpConfigData;
 634
 635   Status         = EFI_SUCCESS;
 636   HttpConfigData = NULL;
 637
 638   if (This == NULL) {
 639     return EFI_INVALID_PARAMETER;
 640   }
 641
 642   OldTpl = gBS->RaiseTPL (TPL_CALLBACK);
 643
 644   Instance = RESTEX_INSTANCE_FROM_THIS (This);
 645
 646   if (RestExConfigData == NULL) {
 647     //
 648     // Set RestExConfigData to NULL means to put EFI REST EX child instance into the unconfigured state.
 649     //
 650     HttpIoDestroyIo (&(Instance->HttpIo));
 651
 652     if (Instance->ConfigData != NULL) {
 653       if (((EFI_REST_EX_HTTP_CONFIG_DATA *)Instance->ConfigData)->HttpConfigData.AccessPoint.IPv4Node != NULL) {
 654         FreePool (((EFI_REST_EX_HTTP_CONFIG_DATA *)Instance->ConfigData)->HttpConfigData.AccessPoint.IPv4Node);
 655       }
 656
 657       FreePool (Instance->ConfigData);
 658       Instance->ConfigData = NULL;
 659     }
 660
 661     Instance->State = RESTEX_STATE_UNCONFIGED;
 662   } else {
 663     HttpConfigData = &((EFI_REST_EX_HTTP_CONFIG_DATA *)RestExConfigData)->HttpConfigData;
 664     Status         = Instance->HttpIo.Http->Configure (Instance->HttpIo.Http, HttpConfigData);
 665     if (EFI_ERROR (Status)) {
 666       goto ON_EXIT;
 667     }
 668
 669     Instance->HttpIo.Timeout = ((EFI_REST_EX_HTTP_CONFIG_DATA *)RestExConfigData)->SendReceiveTimeout;
 670
 671     Instance->ConfigData = AllocateZeroPool (sizeof (EFI_REST_EX_HTTP_CONFIG_DATA));
 672     if (Instance->ConfigData == NULL) {
 673       Status = EFI_OUT_OF_RESOURCES;
 674       goto ON_EXIT;
 675     }
 676
 677     CopyMem (Instance->ConfigData, RestExConfigData, sizeof (EFI_REST_EX_HTTP_CONFIG_DATA));
 678     if (HttpConfigData->LocalAddressIsIPv6 == TRUE) {
 679       ((EFI_REST_EX_HTTP_CONFIG_DATA *)Instance->ConfigData)->HttpConfigData.AccessPoint.IPv6Node = AllocateZeroPool (sizeof (EFI_HTTPv6_ACCESS_POINT));
 680       if (((EFI_REST_EX_HTTP_CONFIG_DATA *)Instance->ConfigData)->HttpConfigData.AccessPoint.IPv6Node == NULL) {
 681         Status = EFI_OUT_OF_RESOURCES;
 682         goto ON_EXIT;
 683       }
 684
 685       CopyMem (
 686         ((EFI_REST_EX_HTTP_CONFIG_DATA *)Instance->ConfigData)->HttpConfigData.AccessPoint.IPv6Node,
 687         HttpConfigData->AccessPoint.IPv6Node,
 688         sizeof (EFI_HTTPv6_ACCESS_POINT)
 689         );
 690     } else {
 691       ((EFI_REST_EX_HTTP_CONFIG_DATA *)Instance->ConfigData)->HttpConfigData.AccessPoint.IPv4Node = AllocateZeroPool (sizeof (EFI_HTTPv4_ACCESS_POINT));
 692       if (((EFI_REST_EX_HTTP_CONFIG_DATA *)Instance->ConfigData)->HttpConfigData.AccessPoint.IPv4Node == NULL) {
 693         Status = EFI_OUT_OF_RESOURCES;
 694         goto ON_EXIT;
 695       }
 696
 697       CopyMem (
 698         ((EFI_REST_EX_HTTP_CONFIG_DATA *)Instance->ConfigData)->HttpConfigData.AccessPoint.IPv4Node,
 699         HttpConfigData->AccessPoint.IPv4Node,
 700         sizeof (EFI_HTTPv4_ACCESS_POINT)
 701         );
 702     }
 703
 704     Instance->State = RESTEX_STATE_CONFIGED;
 705   }
 706
 707 ON_EXIT:
 708   gBS->RestoreTPL (OldTpl);
 709   return Status;
 710 }
 711
 712 /**
 713   This function sends REST request to REST service and signal caller's event asynchronously when
 714   the final response is received by REST EX Protocol driver instance.
 715
 716   The essential design of this function is to handle asynchronous send/receive implicitly according
 717   to REST service asynchronous request mechanism. Caller will get the notification once the response
 718   is returned from REST service.
 719
 720   @param[in]  This                  This is the EFI_REST_EX_PROTOCOL instance.
 721   @param[in]  RequestMessage        This is the HTTP request message sent to REST service. Set RequestMessage
 722                                     to NULL to cancel the previous asynchronous request associated with the
 723                                     corresponding RestExToken. See descriptions for the details.
 724   @param[in]  RestExToken           REST EX token which REST EX Protocol instance uses to notify REST client
 725                                     the status of response of asynchronous REST request. See related definition
 726                                     of EFI_REST_EX_TOKEN.
 727   @param[in]  TimeOutInMilliSeconds The pointer to the timeout in milliseconds which REST EX Protocol driver
 728                                     instance refers as the duration to drop asynchronous REST request. NULL
 729                                     pointer means no timeout for this REST request. REST EX Protocol driver
 730                                     signals caller's event with EFI_STATUS set to EFI_TIMEOUT in RestExToken
 731                                     if REST EX Protocol can't get the response from REST service within
 732                                     TimeOutInMilliSeconds.
 733
 734   @retval EFI_SUCCESS               Asynchronous REST request is established.
 735   @retval EFI_UNSUPPORTED           This REST EX Protocol driver instance doesn't support asynchronous request.
 736   @retval EFI_TIMEOUT               Asynchronous REST request is not established and timeout is expired.
 737   @retval EFI_ABORT                 Previous asynchronous REST request has been canceled.
 738   @retval EFI_DEVICE_ERROR          Otherwise, returns EFI_DEVICE_ERROR for other errors according to HTTP Status Code.
 739   @retval EFI_NOT_READY             The configuration of this instance is not set yet. Configure() must be executed
 740                                     and returns successfully prior to invoke this function.
 741
 742 **/
 743 EFI_STATUS
 744 EFIAPI
 745 RedfishRestExAyncSendReceive (
 746   IN      EFI_REST_EX_PROTOCOL  *This,
 747   IN      EFI_HTTP_MESSAGE      *RequestMessage OPTIONAL,
 748   IN      EFI_REST_EX_TOKEN     *RestExToken,
 749   IN      UINTN                 *TimeOutInMilliSeconds OPTIONAL
 750   )
 751 {
 752   return EFI_UNSUPPORTED;
 753 }
 754
 755 /**
 756   This function sends REST request to a REST Event service and signals caller's event
 757   token asynchronously when the URI resource change event is received by REST EX
 758   Protocol driver instance.
 759
 760   The essential design of this function is to monitor event implicitly according to
 761   REST service event service mechanism. Caller will get the notification if certain
 762   resource is changed.
 763
 764   @param[in]  This                  This is the EFI_REST_EX_PROTOCOL instance.
 765   @param[in]  RequestMessage        This is the HTTP request message sent to REST service. Set RequestMessage
 766                                     to NULL to cancel the previous event service associated with the corresponding
 767                                     RestExToken. See descriptions for the details.
 768   @param[in]  RestExToken           REST EX token which REST EX Protocol driver instance uses to notify REST client
 769                                     the URI resource which monitored by REST client has been changed. See the related
 770                                     definition of EFI_REST_EX_TOKEN in EFI_REST_EX_PROTOCOL.AsyncSendReceive().
 771
 772   @retval EFI_SUCCESS               Asynchronous REST request is established.
 773   @retval EFI_UNSUPPORTED           This REST EX Protocol driver instance doesn't support asynchronous request.
 774   @retval EFI_ABORT                 Previous asynchronous REST request has been canceled or event subscription has been
 775                                     delete from service.
 776   @retval EFI_DEVICE_ERROR          Otherwise, returns EFI_DEVICE_ERROR for other errors according to HTTP Status Code.
 777   @retval EFI_NOT_READY             The configuration of this instance is not set yet. Configure() must be executed
 778                                     and returns successfully prior to invoke this function.
 779
 780 **/
 781 EFI_STATUS
 782 EFIAPI
 783 RedfishRestExEventService (
 784   IN      EFI_REST_EX_PROTOCOL  *This,
 785   IN      EFI_HTTP_MESSAGE      *RequestMessage OPTIONAL,
 786   IN      EFI_REST_EX_TOKEN     *RestExToken
 787   )
 788 {
 789   return EFI_UNSUPPORTED;
 790 }