> For the complete documentation index, see [llms.txt](https://sandbox-docs.verifone.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/system_overview/pg_all_components/pg_emv_tlv_users_guide.md).
# ADK-EMV TLV Utility Programmers Guide
## Preface
The TLV/util library delivered with the EMV-ADK is an optional component that offers BER-TLV (basic encoding rules) and hexadecimal string conversion function. These can be very helpful if an application lacks this functionality.
### Organization
This guide is organized as follows:
[Overview](#sec_emv_tlv_util_overview). Provides an overview of the TLV/util library.
[Programming](#sec_emv_tlv_util_programming). Gives the programming toolset for the library.
[Samples](#sec_emv_tlv_util_samples) Supplies samples and use cases for further development.
## Overview
## Programming
### TLV Path names
Path names are used to access nodes within the tree. The path consists of the ASCII representation of the TLV tags separated by '/'. Nodes before the last '/' must be constructed nodes. The path is given as C string, i.e. it is terminated by a 0-byte. Note that only the following characters are allowed in the path:
"0123456789ABCDEF"
The lowercase characters "abcdef" are not supported and may result in errors.
Example path: "20/21/DF03"
### Import filter callback
The import filter callback allows to remove unwanted data during import to the TLV tree. This allows to import parts of large files that would not fit into memory in whole.
The import filter callback is called just before a node is to be imported, i.e. the node has been created but no content imported yet, and when a node has been completely imported. The filter can then decide whether to keep this node or remove it and whether to stop importing at this point.
The third parameter specifies whether the filter has been called before importing the content of the node (BTLV\_IMPORT\_START) or whether the node is complete (BTLV\_IMPORT\_DONE).
The order the filter callback is called depends on the context. For BTLV\_IMPORT\_START the filter is called for parents first and then for child nodes and for BTLV\_IMPORT\_DONE the import filter is called when the import has been completed for a node, i.e. it is called first for the children and then for the parent.
Note that the filter will not be called for a node with BTLV\_IMPORT\_DONE when the filter already decided to remove the node when called with BTLV\_IMPORT\_START.
Within the import filter the function [xBTLVMatchPath()](/adk-5.0-programmers-guide/readme/files/dir_f2a776acea245b054b8e462971041f2d/dir_a10348dacfa670aa644c1e595a24cf25/dir_2b94011182cccbeeedaa27d80210d4e6/dir_811fc19cda6e4229a2bc03f90d55dff0/btlv_8h.md#acf449e96c5391ef94ada65ae1a246909) is used to check the position of the current node relative to a given path. The following possibilities exist:
* **BTLV\_MATCH** the path of the node is equal to the given path
* **BTLV\_CHILDMATCH** the node is a child of the selected path, e.g. the node has the path "20/20/DF01" and the selected path was "20/20"
* **BTLV\_PARENTMATCH** the node may be a parent of the selected path, e.g. the node has the path "20" and the selected path was "20/20"
* **BTLV\_MISMATCH** the path of the node does not match the selected path.
The filter must return one of the following codes:
* **BTLV\_FLTR\_KEEP** keep the current node and continue importing data
* **BTLV\_FLTR\_REMOVE** remove the current node but continue importing data.
* **BTLV\_FLTR\_DONE** keep the current node and stop importing further nodes. When scanning files for information this can be used to stop reading the file when the desired information has been found.
* **BTLV\_FLTR\_ABORT** remove current node and stop importing further nodes.
Care has to be taken to not inadvertently remove nodes. For example it is not sufficient to keep a node by itself but it is also required to keep the parent nodes, or the node would be deleted when the filter is called for the parent.
Therefore, a typical filter that should keep one node with its children would look like:
```cpp
enum BTLVFilter testfilter(void *pvData, struct BTLVNode *pxRoot, enum BTLVContext context)
{
if(context==BTLV_IMPORT_START) return BTLV_FLTR_KEEP;
if(xBTLVMatchPath(pxRoot,"20/20/20")==BTLV_MISMATCH) return BTLV_FLTR_REMOVE;
return BTLV_FLTR_KEEP;
}
```
It would be an error to return BTLV\_FLTR\_REMOVE if the result of the match was BTLV\_PARENTMATCH, since then the desired node would be removed along with its parent when the filter was later called for the parent node.
The filter function itself may only modify the structure of those parts of the tree for which the importing has been completed or it will corrupt the structure of the tree which may result in a crash. That is the filter may only modify (e.g. delete nodes) the subtree of the current node.
## Samples
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://sandbox-docs.verifone.com/adk-5.0-programmers-guide/readme/system_overview/pg_all_components/pg_emv_tlv_users_guide.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.