resource/csdk/libcoap-4.1.1/block.h

   1 /* block.h -- block transfer
   2  *
   3  * Copyright (C) 2010--2012,2014 Olaf Bergmann <bergmann@tzi.org>
   4  *
   5  * This file is part of the CoAP library libcoap. Please see
   6  * README for terms of use.
   7  */
   8
   9 #ifndef _COAP_BLOCK_H_
  10 #define _COAP_BLOCK_H_
  11
  12 #ifdef __cplusplus
  13 extern "C" {
  14 #endif
  15
  16 #include "option.h"
  17 #include "encode.h"
  18 #include "pdu.h"
  19
  20 /**
  21  * @defgroup block Block Transfer
  22  * @{
  23  */
  24
  25 #ifndef COAP_MAX_BLOCK_SZX
  26 /**
  27  * The largest value for the SZX component in a Block option. Note
  28  * that 1 << (COAP_MAX_BLOCK_SZX + 4) should not exceed
  29  * COAP_MAX_PDU_SIZE.
  30  */
  31 #define COAP_MAX_BLOCK_SZX      4
  32 #endif /* COAP_MAX_BLOCK_SZX */
  33
  34 #if (COAP_MAX_PDU_SIZE - 6) < (1 << (COAP_MAX_BLOCK_SZX + 4))
  35 #error "COAP_MAX_BLOCK_SZX too large"
  36 #endif
  37
  38 /**
  39  * Structure of Block options.
  40  */
  41 typedef struct {
  42   unsigned int num:20;  /**< block number */
  43   unsigned int m:1;     /**< 1 if more blocks follow, 0 otherwise */
  44   unsigned int szx:3;   /**< block size */
  45 } coap_block_t;
  46
  47 /**
  48  * Returns the value of the least significant byte of a Block option @p opt.
  49  * For zero-length options (i.e. num == m == szx == 0), COAP_OPT_BLOCK_LAST
  50  * returns @c NULL.
  51  */
  52 #define COAP_OPT_BLOCK_LAST(opt) \
  53   (COAP_OPT_LENGTH(opt) ? (COAP_OPT_VALUE(opt) + (COAP_OPT_LENGTH(opt)-1)) : 0)
  54
  55 /** Returns the value of the More-bit of a Block option @p opt. */
  56 #define COAP_OPT_BLOCK_MORE(opt) \
  57   (COAP_OPT_LENGTH(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x08) : 0)
  58
  59 /** Returns the value of the SZX-field of a Block option @p opt. */
  60 #define COAP_OPT_BLOCK_SZX(opt)  \
  61   (COAP_OPT_LENGTH(opt) ? (*COAP_OPT_BLOCK_LAST(opt) & 0x07) : 0)
  62
  63 /**
  64  * Returns the value of field @c num in the given block option @p
  65  * block_opt.
  66  */
  67 unsigned int coap_opt_block_num(const coap_opt_t *block_opt);
  68
  69 /**
  70  * Checks if more than @p num blocks are required to deliver @p data_len
  71  * bytes of data for a block size of 1 << (@p szx + 4).
  72  */
  73 static inline int
  74 coap_more_blocks(size_t data_len, unsigned int num, unsigned short szx) {
  75   return ((num+1) << (szx + 4)) < data_len;
  76 }
  77
  78 /** Sets the More-bit in @p block_opt */
  79 static inline void
  80 coap_opt_block_set_m(coap_opt_t *block_opt, int m) {
  81   if (m)
  82     *(COAP_OPT_VALUE(block_opt) + (COAP_OPT_LENGTH(block_opt) - 1)) |= 0x08;
  83   else
  84     *(COAP_OPT_VALUE(block_opt) + (COAP_OPT_LENGTH(block_opt) - 1)) &= ~0x08;
  85 }
  86
  87 /**
  88  * Initializes @p block from @p pdu. @p type must be either COAP_OPTION_BLOCK1
  89  * or COAP_OPTION_BLOCK2. When option @p type was found in @p pdu, @p block
  90  * is initialized with values from this option and the function returns the
  91  * value @c 1. Otherwise, @c 0 is returned.
  92  *
  93  * @param pdu   The pdu to search for option @p type.
  94  * @param type  The option to search for (must be COAP_OPTION_BLOCK1 or
  95  *              COAP_OPTION_BLOCK2)
  96  * @param block The block structure to initilize.
  97  * @return @c 1 on success, @c 0 otherwise.
  98  */
  99 int coap_get_block(coap_pdu_t *pdu, unsigned short type, coap_block_t *block);
 100
 101 /**
 102  * Writes a block option of type @p type to message @p pdu. If the
 103  * requested block size is too large to fit in @p pdu, it is reduced
 104  * accordingly. An exception is made for the final block when less
 105  * space is required. The actual length of the resource is specified
 106  * in @p data_length.
 107  *
 108  * This function may change *block to reflect the values written to
 109  * @p pdu. As the function takes into consideration the remaining space
 110  * @p pdu, no more options should be added after coap_write_block_opt()
 111  * has returned.
 112  *
 113  * @param block      The block structure to use. On return, this object
 114  *                   is updated according to the values that have been
 115  *                   written to @p pdu.
 116  * @param type       COAP_OPTION_BLOCK1 or COAP_OPTION_BLOCK2
 117  * @param pdu        The message where the block option should be
 118  *                   written.
 119  * @param data_length The length of the actual data that will be added
 120  *                   the @p pdu by calling coap_add_block().
 121  * @return @c 1 on success, or a negative value on error.
 122  */
 123 int coap_write_block_opt(coap_block_t *block, unsigned short type,
 124                          coap_pdu_t *pdu, size_t data_length);
 125
 126 /**
 127  * Adds the @p block_num block of size 1 << (@p block_szx + 4) from
 128  * source @p data to @p pdu.
 129  *
 130  * @param pdu    The message to add the block
 131  * @param len    The length of @p data.
 132  * @param data   The source data to fill the block with
 133  * @param block_num The actual block number
 134  * @param block_szx Encoded size of block @p block_number
 135  * @return @c 1 on success, @c 0 otherwise.
 136  */
 137 int coap_add_block(coap_pdu_t *pdu, unsigned int len, const unsigned char *data,
 138                    unsigned int block_num, unsigned char block_szx);
 139 /**@}*/
 140
 141 #ifdef __cplusplus
 142 }
 143 #endif
 144
 145 #endif /* _COAP_BLOCK_H_ */