| Linux NFC User Mode Stack

- Main Page
- Classes
- Files

- File List
- File Members

Classes | Macros | Typedefs | Enumerations | Functions
linux_nfc_api.h File Reference

Go to the source code of this file.

## Classes
struct | nfc_tag_info_t
| NFC tag information structure definition. More...
struct | ndef_info_t
| NFC NDEF Message information structure definition. More...
struct | nfc_btoob_pairing_t
| NFC handover bluetooth record structure definition. More...
struct | nfc_wifi_pairing_t
| NFC wifi handover select record structure definition. More...
struct | nfc_wifi_request_t
| NFC wifi handover request record structure definition. More...
struct | nfc_handover_request_t
| NFC handover request record structure definition. More...
struct | nfc_handover_select_t
| NFC handover select record structure definition. More...
struct | nfcTagCallback_t
| NFC Tag callback function structure definition. More...
struct | nfcSnepServerCallback_t
| NFC SNEP server callback function structure definition. More...
struct | nfcSnepClientCallback_t
| NFC SNEP client callback function structure definition. More...
struct | nfcHostCardEmulationCallback_t
| Host card emulation callback function structure definition. More...
struct | nfcHandoverCallback_t
| Handover callback functions structure definition. More...

## Macros
#define | TARGET_TYPE_UNKNOWN -1
#define | TARGET_TYPE_ISO14443_3A 1
#define | TARGET_TYPE_ISO14443_3B 2
#define | TARGET_TYPE_ISO14443_4 3
#define | TARGET_TYPE_FELICA 4
#define | TARGET_TYPE_ISO15693 5
#define | TARGET_TYPE_NDEF 6
#define | TARGET_TYPE_NDEF_FORMATABLE 7
#define | TARGET_TYPE_MIFARE_CLASSIC 8
#define | TARGET_TYPE_MIFARE_UL 9
#define | TARGET_TYPE_KOVIO_BARCODE 10
#define | TARGET_TYPE_ISO14443_3A_3B 11
#define | DEFAULT_NFA_TECH_MASK (-1)
#define | NFA_TECHNOLOGY_MASK_A 0x01
#define | NFA_TECHNOLOGY_MASK_B 0x02
#define | NFA_TECHNOLOGY_MASK_F 0x04
#define | NFA_TECHNOLOGY_MASK_ISO15693 0x08
#define | NFA_TECHNOLOGY_MASK_KOVIO 0x20
#define | NFA_TECHNOLOGY_MASK_A_ACTIVE 0x40
#define | NFA_TECHNOLOGY_MASK_F_ACTIVE 0x80
#define | NFA_TECHNOLOGY_MASK_ALL 0xFF
#define | NDEF_TNF_EMPTY 0
#define | NDEF_TNF_WELLKNOWN 1
#define | NDEF_TNF_MEDIA 2
#define | NDEF_TNF_URI 3
#define | NDEF_TNF_EXT 4
#define | NDEF_TNF_UNKNOWN 5
#define | NDEF_TNF_UNCHANGED 6
#define | NFA_PROTOCOL_UNKNOWN 0x00
#define | NFA_PROTOCOL_T1T 0x01
#define | NFA_PROTOCOL_T2T 0x02
#define | NFA_PROTOCOL_T3T 0x03
#define | NFA_PROTOCOL_ISO_DEP 0x04
#define | NFA_PROTOCOL_15693 0x06
#define | NFA_PROTOCOL_MIFARE 0x80
#define | FLAG_HCE_SKIP_NDEF_CHECK 0x80
| setting this flag allows host application ignore an NDEF check command from reader More...
#define | FLAG_HCE_ENABLE_HCE 0x01
| setting this flag allows host application enable HCE More...

## Typedefs
typedef unsigned char | tNFC_PROTOCOL
typedef struct nfc_btoob_pairing_t | nfc_btoob_request_t

## Enumerations
enum | nfc_friendly_type_t { NDEF_FRIENDLY_TYPE_TEXT = 0, NDEF_FRIENDLY_TYPE_URL = 1, NDEF_FRIENDLY_TYPE_HS = 2, NDEF_FRIENDLY_TYPE_HR = 3, NDEF_FRIENDLY_TYPE_OTHER = 4 }
| friendly NDEF Type Name More...
enum | nfc_handover_bt_type_t { HANDOVER_TYPE_UNKNOWN = 0, HANDOVER_TYPE_BT, HANDOVER_TYPE_BLE }
| Bluetooth Handover Cofiguration Type Name. More...
enum | nfc_handover_cps_t { HANDOVER_CPS_INACTIVE = 0, HANDOVER_CPS_ACTIVE = 1, HANDOVER_CPS_ACTIVATING = 2, HANDOVER_CPS_UNKNOWN = 3 }
| Handover Carrier Power State definitions. More...

## Functions
int | ndef_readText (unsigned char *ndef_buff, unsigned int ndef_buff_length, char *out_text, unsigned int out_text_length)
| read text message from NDEF data. More...
int | ndef_readUrl (unsigned char *ndef_buff, unsigned int ndef_buff_length, char *out_url, unsigned int out_url_length)
| read uri message from NDEF data. More...
int | ndef_readHandoverSelectInfo (unsigned char *ndef_buff, unsigned int ndef_buff_length, nfc_handover_select_t *info)
| read handover select message from NDEF data. More...
int | ndef_readHandoverRequestInfo (unsigned char *ndef_buff, unsigned int ndef_buff_length, nfc_handover_request_t *info)
| read handover request message from NDEF data. More...
int | ndef_createUri (char *uri, unsigned char *out_ndef_buff, unsigned int out_ndef_buff_length)
| Create a new NDEF Record containing a URI. More...
int | ndef_createText (char *language_code, char *text, unsigned char *out_ndef_buff, unsigned int out_ndef_buff_length)
| Create a new NDEF Record containing a text. More...
int | ndef_createMime (char *mime_type, unsigned char *mime_data, unsigned int mime_data_length, unsigned char *out_ndef_buff, unsigned int out_ndef_buff_length)
| Create a new NDEF Record containing MIME data. More...
int | ndef_createHandoverSelect (nfc_handover_cps_t cps, char *carrier_data_ref, unsigned char *ndef_buff, unsigned int ndef_buff_length, unsigned char *out_ndef_buff, unsigned int out_ndef_buff_length)
| Create a new NDEF Record containing Handover Select message. More...
int | nfcTag_isNdef (unsigned int handle, ndef_info_t *info)
| Check if the tag is Ndef formated. More...
int | nfcTag_readNdef (unsigned int handle, unsigned char *ndef_buffer, unsigned int ndef_buffer_length, nfc_friendly_type_t *friendly_ndef_type)
| Read ndef message from tag. More...
int | nfcTag_writeNdef (unsigned int handle, unsigned char *ndef_buffer, unsigned int ndef_buffer_length)
| Write ndef message to tag. More...
int | nfcTag_makeReadOnly (unsigned int handle)
| Make the tag read-only. More...
int | nfcTag_switchRF (unsigned int handle, int is_frame_rf)
| Switch RF interface for ISO-DEP and MifareClassic tag. More...
int | nfcTag_transceive (unsigned int handle, unsigned char *tx_buffer, int tx_buffer_length, unsigned char *rx_buffer, int rx_buffer_length, unsigned int timeout)
| Send raw command to tag. More...
int | nfcManager_doInitialize ()
| initialize nfc stack. More...
int | nfcManager_doDeinitialize ()
| de-initialize nfc stack. More...
int | nfcManager_isNfcActive ()
void | nfcManager_enableDiscovery (int technologies_masks, int reader_only_mode, int enable_host_routing, int restart)
| Start nfc discovery. More...
void | nfcManager_disableDiscovery ()
| Stop polling and listening for devices. More...
void | nfcManager_registerTagCallback (nfcTagCallback_t *callback)
| Register a tag callback functions. More...
void | nfcManager_deregisterTagCallback ()
| Deregister a tag callback functions. More...
int | nfcManager_getFwVersion ()
| Return FW version. More...
int | nfcSnep_registerClientCallback (nfcSnepClientCallback_t *client_callback)
| Register a callback functions for snep client. More...
void | nfcSnep_deregisterClientCallback ()
| Deregister a callback functions for snep client. More...
int | nfcSnep_startServer (nfcSnepServerCallback_t *server_callback)
| Start a snep server to receive snep message. More...
void | nfcSnep_stopServer ()
| Stop senp server. More...
int | nfcSnep_putMessage (unsigned char *msg, unsigned int length)
| put a snep message to remote snep server. More...
void | nfcHce_registerHceCallback (nfcHostCardEmulationCallback_t *callback)
| Register a callback functions for host card emulation. More...
void | nfcHce_deregisterHceCallback ()
| Deregister the host card emulation callback. More...
int | nfcHce_sendCommand (unsigned char *command, unsigned int command_length)
| Send Apdu to remote reader. More...
int | nfcHo_registerCallback (nfcHandoverCallback_t *callback)
| Register the handover callback. More...
void | nfcHo_deregisterCallback ()
| Deregister the handover callback. More...
int | nfcHo_sendSelectRecord (unsigned char *message, unsigned int length)
| Send Handover Select Message to remote device. More...
int | nfcHo_sendSelectError (unsigned int reason, unsigned int data)
| Send Handover select error to remote device. More...

## Macro Definition Documentation

#define DEFAULT_NFA_TECH_MASK (-1)

Definition at line 41 of file linux_nfc_api.h.

#define FLAG_HCE_ENABLE_HCE 0x01

setting this flag allows host application enable HCE

Definition at line 93 of file linux_nfc_api.h.

#define FLAG_HCE_SKIP_NDEF_CHECK 0x80

setting this flag allows host application ignore an NDEF check command from reader

Definition at line 89 of file linux_nfc_api.h.

#define NDEF_TNF_EMPTY 0

Empty (type/id/payload len =0)

Definition at line 61 of file linux_nfc_api.h.

#define NDEF_TNF_EXT 4

NFC Forum external type/RTD

Definition at line 69 of file linux_nfc_api.h.

#define NDEF_TNF_MEDIA 2

Media-type as defined in RFC 2046

Definition at line 65 of file linux_nfc_api.h.

#define NDEF_TNF_UNCHANGED 6

Unchanged (type len =0)

Definition at line 73 of file linux_nfc_api.h.

#define NDEF_TNF_UNKNOWN 5

Unknown (type len =0)

Definition at line 71 of file linux_nfc_api.h.

#define NDEF_TNF_URI 3

Absolute URI as defined in RFC 3986

Definition at line 67 of file linux_nfc_api.h.

#define NDEF_TNF_WELLKNOWN 1

NFC Forum well-known type/RTD

Definition at line 63 of file linux_nfc_api.h.

#define NFA_PROTOCOL_15693 0x06

Definition at line 81 of file linux_nfc_api.h.

#define NFA_PROTOCOL_ISO_DEP 0x04

Definition at line 80 of file linux_nfc_api.h.

#define NFA_PROTOCOL_MIFARE 0x80

Definition at line 82 of file linux_nfc_api.h.

#define NFA_PROTOCOL_T1T 0x01

Definition at line 77 of file linux_nfc_api.h.

#define NFA_PROTOCOL_T2T 0x02

Definition at line 78 of file linux_nfc_api.h.

#define NFA_PROTOCOL_T3T 0x03

Definition at line 79 of file linux_nfc_api.h.

#define NFA_PROTOCOL_UNKNOWN 0x00

Definition at line 76 of file linux_nfc_api.h.

#define NFA_TECHNOLOGY_MASK_A 0x01

NFC Technology A

Definition at line 43 of file linux_nfc_api.h.

#define NFA_TECHNOLOGY_MASK_A_ACTIVE 0x40

NFC Technology A active mode

Definition at line 53 of file linux_nfc_api.h.

#define NFA_TECHNOLOGY_MASK_ALL 0xFF

All supported technologies

Definition at line 57 of file linux_nfc_api.h.

#define NFA_TECHNOLOGY_MASK_B 0x02

NFC Technology B

Definition at line 45 of file linux_nfc_api.h.

#define NFA_TECHNOLOGY_MASK_F 0x04

NFC Technology F

Definition at line 47 of file linux_nfc_api.h.

#define NFA_TECHNOLOGY_MASK_F_ACTIVE 0x80

NFC Technology F active mode

Definition at line 55 of file linux_nfc_api.h.

#define NFA_TECHNOLOGY_MASK_ISO15693 0x08

Proprietary Technology

Definition at line 49 of file linux_nfc_api.h.

#define NFA_TECHNOLOGY_MASK_KOVIO 0x20

Proprietary Technology

Definition at line 51 of file linux_nfc_api.h.

#define TARGET_TYPE_FELICA 4

Definition at line 31 of file linux_nfc_api.h.

#define TARGET_TYPE_ISO14443_3A 1

Definition at line 28 of file linux_nfc_api.h.

#define TARGET_TYPE_ISO14443_3A_3B 11

Definition at line 38 of file linux_nfc_api.h.

#define TARGET_TYPE_ISO14443_3B 2

Definition at line 29 of file linux_nfc_api.h.

#define TARGET_TYPE_ISO14443_4 3

Definition at line 30 of file linux_nfc_api.h.

#define TARGET_TYPE_ISO15693 5

Definition at line 32 of file linux_nfc_api.h.

#define TARGET_TYPE_KOVIO_BARCODE 10

Definition at line 37 of file linux_nfc_api.h.

#define TARGET_TYPE_MIFARE_CLASSIC 8

Definition at line 35 of file linux_nfc_api.h.

#define TARGET_TYPE_MIFARE_UL 9

Definition at line 36 of file linux_nfc_api.h.

#define TARGET_TYPE_NDEF 6

Definition at line 33 of file linux_nfc_api.h.

#define TARGET_TYPE_NDEF_FORMATABLE 7

Definition at line 34 of file linux_nfc_api.h.

#define TARGET_TYPE_UNKNOWN -1

Definition at line 27 of file linux_nfc_api.h.

## Typedef Documentation

typedef struct nfc_btoob_pairing_t nfc_btoob_request_t

typedef unsigned char tNFC_PROTOCOL

Definition at line 83 of file linux_nfc_api.h.

## Enumeration Type Documentation

enum nfc_friendly_type_t

friendly NDEF Type Name

Enumerator
NDEF_FRIENDLY_TYPE_TEXT | NDEF text: NFC Forum well-known type + RTD: 0x55.
NDEF_FRIENDLY_TYPE_URL |
NDEF_FRIENDLY_TYPE_HS |
NDEF_FRIENDLY_TYPE_HR |
NDEF_FRIENDLY_TYPE_OTHER |

Definition at line 98 of file linux_nfc_api.h.

enum nfc_handover_bt_type_t

Bluetooth Handover Cofiguration Type Name.

Enumerator
HANDOVER_TYPE_UNKNOWN | indicates this is not a handover bluetooth record
HANDOVER_TYPE_BT | NFC Forum handover bluetooth record.
HANDOVER_TYPE_BLE | indicates NFC Forum handover BLE record

Definition at line 124 of file linux_nfc_api.h.

enum nfc_handover_cps_t

Handover Carrier Power State definitions.

Enumerator
HANDOVER_CPS_INACTIVE | indicates the carrier is currently off
HANDOVER_CPS_ACTIVE | indicates the carrier is currently on
HANDOVER_CPS_ACTIVATING | indicates the carrier is in the process of activation
HANDOVER_CPS_UNKNOWN | indicates the carrier power state is unknown

Definition at line 142 of file linux_nfc_api.h.

## Function Documentation

int ndef_createHandoverSelect | ( | nfc_handover_cps_t | cps,
|  | char * | carrier_data_ref,
|  | unsigned char * | ndef_buff,
|  | unsigned int | ndef_buff_length,
|  | unsigned char * | out_ndef_buff,
|  | unsigned int | out_ndef_buff_length
| ) |  |

Create a new NDEF Record containing Handover Select message.

Parameters

  cps | Carrier power state
  carrier_data_ref | carrier data reference name
  ndef_buff | carrier configuration record
  ndef_buff_length | carrier configuration record length
  out_ndef_buff | the buffer to store handover select message
  out_ndef_buff_length | the length of handover select message

Returns
  the length of NDEF buffer be used.

int ndef_createMime | ( | char * | mime_type,
|  | unsigned char * | mime_data,
|  | unsigned int | mime_data_length,
|  | unsigned char * | out_ndef_buff,
|  | unsigned int | out_ndef_buff_length
| ) |  |

Create a new NDEF Record containing MIME data.

Parameters

  mime_type | a valid MIME type
  mime_data | MIME data as bytes array
  mime_data_length | MIME data length
  out_ndef_buff | the buffer to store ndef message
  out_ndef_buff_length | the length of ndef buffer

Returns
  the length of NDEF buffer be used.

int ndef_createText | ( | char * | language_code,
|  | char * | text,
|  | unsigned char * | out_ndef_buff,
|  | unsigned int | out_ndef_buff_length
| ) |  |

Create a new NDEF Record containing a text.

Parameters

  language_code | language encoding code
  text | text to be written
  out_ndef_buff | the buffer to store ndef message
  out_ndef_buff_length | the length of ndef buffer

Returns
  the length of NDEF buffer be used.

int ndef_createUri | ( | char * | uri,
|  | unsigned char * | out_ndef_buff,
|  | unsigned int | out_ndef_buff_length
| ) |  |

Create a new NDEF Record containing a URI.

Parameters

  uri | the uri to be written
  out_ndef_buff | the buffer to store ndef message
  out_ndef_buff_length | the length of ndef buffer

Returns
  the length of NDEF buffer be used.

int ndef_readHandoverRequestInfo | ( | unsigned char * | ndef_buff,
|  | unsigned int | ndef_buff_length,
|  | nfc_handover_request_t * | info
| ) |  |

read handover request message from NDEF data.

Parameters

  ndef_buff | the buffer with handover ndef message
  ndef_buff_length | the length of handover ndef message
  info | handover request information to be filled

Returns
  0 if success, otherwise failed.

int ndef_readHandoverSelectInfo | ( | unsigned char * | ndef_buff,
|  | unsigned int | ndef_buff_length,
|  | nfc_handover_select_t * | info
| ) |  |

read handover select message from NDEF data.

Parameters

  ndef_buff | the buffer with handover ndef message
  ndef_buff_length | the length of handover ndef message
  info | handover select information to be filled

Returns
  0 if success, otherwise failed.

int ndef_readText | ( | unsigned char * | ndef_buff,
|  | unsigned int | ndef_buff_length,
|  | char * | out_text,
|  | unsigned int | out_text_length
| ) |  |

read text message from NDEF data.

Parameters

  ndef_buff | the buffer with ndef message
  ndef_buff_length | the length of buffer
  out_text | the buffer to fill text in
  out_text_length | the length of out_text buffer

Returns
  0 if success, otherwise failed.

int ndef_readUrl | ( | unsigned char * | ndef_buff,
|  | unsigned int | ndef_buff_length,
|  | char * | out_url,
|  | unsigned int | out_url_length
| ) |  |

read uri message from NDEF data.

Parameters

  ndef_buff | the buffer with ndef message
  ndef_buff_length | the length of buffer
  out_url | the buffer to fill url in
  out_url_length | the length of out_url buffer

Returns
  0 if success, otherwise failed.

void nfcHce_deregisterHceCallback | ( |  | ) |

Deregister the host card emulation callback.

Returns
  None

void nfcHce_registerHceCallback | ( | nfcHostCardEmulationCallback_t * | callback | ) |

Register a callback functions for host card emulation.

Parameters

  callback | host card emualtion callback functions.

Returns
  None

int nfcHce_sendCommand | ( | unsigned char * | command,
|  | unsigned int | command_length
| ) |  |

Send Apdu to remote reader.

Parameters

  command | apdu package to be sent.
  command_length | apdu package length

Returns
  0 if success, otherwise failed.

void nfcHo_deregisterCallback | ( |  | ) |

Deregister the handover callback.

Returns
  None

int nfcHo_registerCallback | ( | nfcHandoverCallback_t * | callback | ) |

Register the handover callback.

Parameters

  callback | handover callback functions.

Returns
  0 if success, otherwise failed.

int nfcHo_sendSelectError | ( | unsigned int | reason,
|  | unsigned int | data
| ) |  |

Send Handover select error to remote device.

Parameters

  reason | error reason.
  data | error data.

Returns
  0 if success, otherwise failed.

int nfcHo_sendSelectRecord | ( | unsigned char * | message,
|  | unsigned int | length
| ) |  |

Send Handover Select Message to remote device.

Parameters

  message | handover Select message.
  length | handover Select message length.

Returns
  0 if success, otherwise failed.

void nfcManager_deregisterTagCallback | ( |  | ) |

Deregister a tag callback functions.

Returns
  None

void nfcManager_disableDiscovery | ( |  | ) |

Stop polling and listening for devices.

Returns
  None

int nfcManager_doDeinitialize | ( |  | ) |

de-initialize nfc stack.

Returns
  0 if success, otherwise failed.

int nfcManager_doInitialize | ( |  | ) |

initialize nfc stack.

Returns
  0 if success, otherwise failed.

void nfcManager_enableDiscovery | ( | int | technologies_masks,
|  | int | reader_only_mode,
|  | int | enable_host_routing,
|  | int | restart
| ) |  |

Start nfc discovery.

Parameters

  technologies_masks | Nfc technology mask.
  reader_only_mode | indicates if enable reader only mode. (Means no P2P or HCE)
  enable_host_routing | indicates if enable host card emualtion
  restart | indicates if force restart discovery

Returns
  0 if success, otherwise failed.

int nfcManager_getFwVersion | ( |  | ) |

Return FW version.

Returns
  FW version on chip, return 0 if fails.

int nfcManager_isNfcActive | ( |  | ) |

void nfcManager_registerTagCallback | ( | nfcTagCallback_t * | callback | ) |

Register a tag callback functions.

Parameters

  callback | tag callback functions.

Returns
  None

void nfcSnep_deregisterClientCallback | ( |  | ) |

Deregister a callback functions for snep client.

Returns
  None

int nfcSnep_putMessage | ( | unsigned char * | msg,
|  | unsigned int | length
| ) |  |

put a snep message to remote snep server.

Parameters

  msg | snep message.
  length | snep message length.

Returns
  0 if success, otherwise failed.

int nfcSnep_registerClientCallback | ( | nfcSnepClientCallback_t * | client_callback | ) |

Register a callback functions for snep client.

Parameters

  client_callback | snep client callback functions.

Returns
  0 if success

int nfcSnep_startServer | ( | nfcSnepServerCallback_t * | server_callback | ) |

Start a snep server to receive snep message.

Parameters

  server_callback | snep server callback functions.

Returns
  0 if success

void nfcSnep_stopServer | ( |  | ) |

Stop senp server.

Returns
  None

int nfcTag_isNdef | ( | unsigned int | handle,
|  | ndef_info_t * | info
| ) |  |

Check if the tag is Ndef formated.

Parameters

  handle | handle to the tag.
  info | information about tag to be retreived

Returns
  1 with info if it is Ndef tag, otherwise 0.

int nfcTag_makeReadOnly | ( | unsigned int | handle | ) |

Make the tag read-only.

Parameters

  handle | handle to the tag.

Returns
  0 if success, otherwise failed.

int nfcTag_readNdef | ( | unsigned int | handle,
|  | unsigned char * | ndef_buffer,
|  | unsigned int | ndef_buffer_length,
|  | nfc_friendly_type_t * | friendly_ndef_type
| ) |  |

Read ndef message from tag.

Parameters

  handle | handle to the tag.
  ndef_buffer | the buffer to be filled with ndef message
  ndef_buffer_length | the length of buffer
  friendly_ndef_type | the friendly ndef type of ndef message

Returns
  the length of ndef message if success, otherwise -1.

int nfcTag_switchRF | ( | unsigned int | handle,
|  | int | is_frame_rf
| ) |  |

Switch RF interface for ISO-DEP and MifareClassic tag.

Parameters

  handle | handle to the tag.
  is_frame_rf | indicates if the target RF interface is Frame RF or not.

Returns
  0 if success, otherwise failed.

int nfcTag_transceive | ( | unsigned int | handle,
|  | unsigned char * | tx_buffer,
|  | int | tx_buffer_length,
|  | unsigned char * | rx_buffer,
|  | int | rx_buffer_length,
|  | unsigned int | timeout
| ) |  |

Send raw command to tag.

Parameters

  handle | handle to the tag.
  tx_buffer | the buffer to be sent
  tx_buffer_length | the length of send buffer
  rx_buffer | the receive buffer to be filled
  rx_buffer_length | the length of receive buffer
  timeout | the timeout value in milliseconds

Returns
  the real length of data received or 0 if failed.

int nfcTag_writeNdef | ( | unsigned int | handle,
|  | unsigned char * | ndef_buffer,
|  | unsigned int | ndef_buffer_length
| ) |  |

Write ndef message to tag.

Parameters

  handle | handle to the tag.
  ndef_buffer | the buffer with ndef message
  ndef_buffer_length | the length of buffer

Returns
  if success, otherwise failed.