block access functions

Functions
static int	cbmimage_i_adjust_relative_address (cbmimage_fileimage *image, cbmimage_blockaddress *block)
uint8_t *	cbmimage_i_get_address_of_block (cbmimage_fileimage *image, cbmimage_blockaddress block)
int	cbmimage_read_block (cbmimage_fileimage *image, cbmimage_blockaddress block, void *buffer, size_t buffersize)
	read a block from the image and copy it into the provided buffer
int	cbmimage_write_block (cbmimage_fileimage *image, cbmimage_blockaddress block, void *buffer, size_t buffersize)
	write a block to the image by copying it from the provided buffer
int	cbmimage_read_next_block (cbmimage_fileimage *image, cbmimage_blockaddress *block, void *buffer, size_t buffersize)
	read the next block from the image and copy it into the provided buffer

Detailed Description

Function Documentation

cbmimage_i_adjust_relative_address()

static int cbmimage_i_adjust_relative_address ( cbmimage_fileimage * image, cbmimage_blockaddress * block )

static

adjust a relative address to a global address

Parameters

[in]	image	pointer to the image data
[in]	block	pointer to the block address for the block that is of interest

Returns

• 0 if the block lies in the current subdir
• -1 if an error occurred

cbmimage_i_get_address_of_block()

uint8_t * cbmimage_i_get_address_of_block	(	cbmimage_fileimage *	image,
		cbmimage_blockaddress	block )

get the address of a block

Parameters

[in]	image	pointer to the image data
[in]	block	pointer to the block address for the block that is of interest

Returns

pointer to the beginning of the block inside of the image memory

Remarks

• This function is for internal purposes only.
  Do not access from outside of the library, as it is subject to change!

Bug

• There is no error checking on the provided block.
  That is, if the block does not exist, this function will happily provide an undefined pointer!

cbmimage_read_block()

int cbmimage_read_block	(	cbmimage_fileimage *	image,
		cbmimage_blockaddress	block,
		void *	buffer,
		size_t	buffersize )

read a block from the image and copy it into the provided buffer

Parameters

[in]	image	pointer to the image data
[in]	block	pointer to the block address for the block that is of interest
[out]	buffer	pointer to the buffer that will contain the block contents on termination
[in]	buffersize	the size of the buffer pointed to by the parameter buffer

Returns

• 0 if the block is available and full (that is, it contains another link, so all byte are relevant)
• > 0: this is the last block, the return gives the number of valid byte in this block. For example, if the link of this last block is (0,x), it will return the value x.
• -1 if an error occurred

Remarks

• If the buffersize is not big enough, that is, it is not at least cbmimage_get_bytes_in_block() byte long, this function does nothing. It does not even provide a partial copy of the data in this case!

cbmimage_read_next_block()

int cbmimage_read_next_block	(	cbmimage_fileimage *	image,
		cbmimage_blockaddress *	block,
		void *	buffer,
		size_t	buffersize )

read the next block from the image and copy it into the provided buffer

The next block is the next one according to the chain at the beginning of the block.

Parameters

[in]	image	pointer to the image data
[out]	block	pointer to the block address that will get the block address that has been read on termination
[in,out]	buffer	pointer to the buffer that has the link address, and that will contain the contents of the new block on termination
[in]	buffersize	the size of the buffer pointed to by the parameter buffer

Returns

• 0 if the next block is available and full (that is, it contains another link, so all byte are relevant)
• > 0: this is the last block, the return gives the number of valid byte in this block. For example, if the link of this last block is (0,x), it will return the value x.
• -1 if an error occurred, for example, there is no next block

Remarks

• If the buffersize is not big enough, that is, it is not at least cbmimage_get_bytes_in_block() byte long, this function does nothing. It does not even provide a partial copy of the data in this case!
• If you want to read all the blocks of a file, call this function repeatedly until you get a -1 as return value.

Bug

• There is no error checking on the provided link in the block.
  That is, if the linked to block does not exist, this function will happily provide an undefined pointer!

cbmimage_write_block()

int cbmimage_write_block	(	cbmimage_fileimage *	image,
		cbmimage_blockaddress	block,
		void *	buffer,
		size_t	buffersize )

write a block to the image by copying it from the provided buffer

Parameters

[in]	image	pointer to the image data
[in]	block	pointer to the block address for the block that is of interest
[in]	buffer	pointer to the buffer that has the contents that are to be written into the image
[in]	buffersize	the size of the buffer pointed to by the parameter buffer

Returns

• 0 if the block is available
• -1 if an error occurred

Remarks

• If the buffersize is not big enough, that is, it is not at least cbmimage_get_bytes_in_block() byte long, this function does nothing. It does not even partially copy the data in this case!