source: svn/newcon3bcm2_21bu/nexus/app/dta/image_recv.h @ 22

/***************************************************************************
 *     Copyright (c) 2003-2008, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile: $
 * $brcm_Revision: $
 * $brcm_Date: $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log: $
 * 
 *
 ***************************************************************************/
#if !defined(__IMAGE_RECV_H__)
#define __IMAGE_RECV_H__

#include "bapp_types.h"

/***************************************************************************
Summary:
 Error codes returned by image functions
Description:
 Error codes that are returned by image... functions. Caller must test
these error codes and update status accordingly.
***************************************************************************/
#define berr_no_dsmcc_pid 41
#define berr_no_code_image_file 42
#define berr_download_failure 43
#define berr_no_memory 44
#define berr_verification_falure 45
#define berr_loading 46
#define berr_same_version 47

/***************************************************************************
Summary:
 Structure describing received software image in memory.
Description:
 Structure is placed at the head of received image.
 size - size of the image.
 data - content of the software image. The actual array has at least as many
 bytes as the size of the image. The remaining bytes follow the first element
 of the array - data[1], data[2]...
***************************************************************************/
struct image_t {
    size_t size;
    char data[1];
};

/***************************************************************************
Summary: 
  Initialize image download.
Description:
  Initialize image download and prepare for receiving image. This function 
should be called before calling any other function. There is no corresponding
close function.
Input:
  None
Output:
  None
Returns:
  b_ok in case call was successful, error code otherwise.
SeeAlso:
None
***************************************************************************/
bresult image_init(void);

/***************************************************************************
Summary:
  Receive image from the dsmcc carousel
Description:
  Receive image from the dsmcc carousel. The function first receives dii,
parses it, then receives first module described in dii. The result is stored
in memory block described by image_t structure and allocated inside of the
function. After caller is done with the image it must call free(image) in
order to avoid memory leak. Since image is large memory leak will be 
significant. Function does not do any tuning so tuning should be done before
calling this function.
Input:
  band - input band on which to receive data.
  pid - pid which contains dsm-cc data.
  image - pointer to pointer to the image structure.
  name_lengh - lenght of name from CVT
  name - pointer to the name from CVT
Output:
  image - if function is successful this pointer will be initialize with
pointer to the image_t structure containing received image. If function
fails content of this pointer is not defined. After application is done with
data the this pointer should be freed by calling free.
Returns:
  b_ok if function is successful error code otherwise.
SeeAlso:
  image_init
***************************************************************************/
bresult image_receive(bband_t band, uint16_t pid, struct image_t ** image, uint8_t name_length, uint8_t * name);

/***************************************************************************
Summary:
  Write image to flash
Description:
  Function chooses which location to use for storing image based on image
version and running image version. Then function authenticates image and 
if authentication successful, writes image to flash.
Input:
  image - pointer to the image structure.
Output:
  None
Returns:
  b_ok if function is successful error code otherwise.
SeeAlso:
  image_init, image_receive
***************************************************************************/
bresult image_write(struct image_t * image);

#endif