doc/filetransfer_mainpage.h

   1 /** \mainpage DLT Filetransfer Main documentation page
   2
   3 \section Introduction Introduction
   4 DLT Filetransfer enables the feature to store the binary data of a file to the automotive dlt log. The file will
   5 be read in binary mode and put as payload to a DLT_INFO log. With a special plugin of the dlt viewer, you can
   6 extract the file from the trace and save it to your hard disk.
   7
   8
   9 \section Protocol Protocol
  10 The file transfer is at least one single transaction. This transaction consist of three main types of packages:
  11         \li header package
  12         \li one or more data packages
  13         \li end package
  14
  15 The following section explains more about the content of each package.
  16
  17 \subsection Header Header Package
  18 Every filetransfer must begin with the header package using:
  19 \code
  20 int dlt_user_log_file_header(DltContext *fileContext,const char *filename)
  21 \endcode
  22 Here's the conent of the header package:
  23 \code
  24 |----------------------------------------------------|
  25 |                      FLST                          | Package flag
  26 |----------------------------------------------------|
  27 |                fileserialnumber                    | Inode of the file used as file serialnumber
  28 |----------------------------------------------------|
  29 |                    filename                        | Use the absolute filepath to the file
  30 |----------------------------------------------------|
  31 |                    filesize                        | Filesize of the file
  32 |----------------------------------------------------|
  33 |               file creation date                   | Creation date of the file
  34 |----------------------------------------------------|
  35 |               number of packages                   | Counted packages which will be transferred in the data packages
  36 |----------------------------------------------------|
  37 |                   BUFFER_SIZE                      | Defined buffer size to reconstruct the file
  38 |----------------------------------------------------|
  39 |                      FLST                          | Package flag
  40 |----------------------------------------------------|
  41 \endcode
  42
  43 \subsection Data Data Package
  44 After the header package was sent, at least one or more data packages can be send using:
  45 \code
  46 int dlt_user_log_file_data(DltContext *fileContext,const char *filename, int packageToTransfer, int timeout)
  47 \endcode
  48 Here's the conent of the data package:
  49 \code
  50 |----------------------------------------------------|
  51 |                      FLDA                          | Package flag
  52 |----------------------------------------------------|
  53 |                fileserialnumber                    | Inode of the file used as file serialnumber
  54 |----------------------------------------------------|
  55 |                  PackageNumber                     | Transferred package
  56 |----------------------------------------------------|
  57 |                      Data                          | Payload containing data
  58 |----------------------------------------------------|
  59 |                      FLDA                          | Package flag
  60 |----------------------------------------------------|
  61 \endcode
  62
  63
  64 \subsection End End Package
  65 After all data packages were sent, the end package must be sent to indicate that the filetransfer is over using:
  66 \code
  67 int dlt_user_log_file_end(DltContext *fileContext,const char *filename,int deleteFlag)
  68 \endcode
  69 Here's the conent of the end package:
  70 \code
  71 |----------------------------------------------------|
  72 |                      FLFI                          | Package flag
  73 |----------------------------------------------------|
  74 |                fileserialnumber                    | Inode of the file
  75 |----------------------------------------------------|
  76 |                      FLFI                          | Package flag
  77 |----------------------------------------------------|
  78 \endcode
  79 \subsection File information
  80 The library offers the user the possibility to log informations about a file using the following method without transferring the file itself using:
  81 \code
  82 dlt_user_log_file_infoAbout(DltContext *fileContext, const char *filename)
  83 \endcode
  84 Here is the content of the information package:
  85 \code
  86 |----------------------------------------------------|
  87 |                      FLIF                          | Package flag
  88 |----------------------------------------------------|
  89 |                fileserialnumber                    | Inode of the file used as file serialnumber
  90 |----------------------------------------------------|
  91 |                    filename                        | Use the absolute filepath to the file
  92 |----------------------------------------------------|
  93 |                    filesize                        | Filesize of the file
  94 |----------------------------------------------------|
  95 |               file creation date                   | Creation date of the file
  96 |----------------------------------------------------|
  97 |               number of packages                   | Counted packages which will be transferred in the data packages
  98 |----------------------------------------------------|
  99 |                      FLIF                          | Package flag
 100 |----------------------------------------------------|
 101 \endcode
 102
 103 \subsection File transfer error
 104 \code
 105 //! Error code for dlt_user_log_file_complete
 106 #define ERROR_FILE_COMPLETE -300
 107 //! Error code for dlt_user_log_file_complete
 108 #define ERROR_FILE_COMPLETE1 -301
 109 //! Error code for dlt_user_log_file_complete
 110 #define ERROR_FILE_COMPLETE2 -302
 111 //! Error code for dlt_user_log_file_complete
 112 #define ERROR_FILE_COMPLETE3 -303
 113 //! Error code for dlt_user_log_file_head
 114 #define ERROR_FILE_HEAD -400
 115 //! Error code for dlt_user_log_file_data
 116 #define ERROR_FILE_DATA -500
 117 //! Error code for dlt_user_log_file_data
 118 #define DLT_FILETRANSFER_ERROR_FILE_DATA_USER_BUFFER_FAILED -501
 119 //! Error code for dlt_user_log_file_end
 120 #define ERROR_FILE_END -600
 121 //! Error code for dlt_user_log_file_infoAbout
 122 #define ERROR_INFO_ABOUT -700
 123 //! Error code for dlt_user_log_file_packagesCount
 124 #define ERROR_PACKAGE_COUNT -800
 125 \endcode
 126 If an error happens during file transfer, the library will execute the mehtod:
 127 \code
 128 void dlt_user_log_file_errorMessage(DltContext *fileContext, const char *filename, int errorCode)
 129 \endcode
 130 Here is the content of the error package:
 131 \code
 132 |----------------------------------------------------|
 133 |                      FLER                          | Package flag
 134 |----------------------------------------------------|
 135 |                   error code                       | see error codes above
 136 |----------------------------------------------------|
 137 |                linux error code                    | standard linux error code
 138 |----------------------------------------------------|
 139 |                fileserialnumber                    | Inode of the file used as file serialnumber
 140 |----------------------------------------------------|
 141 |                    filename                        | Use the absolute filepath to the file
 142 |----------------------------------------------------|
 143 |                    filesize                        | Filesize of the file
 144 |----------------------------------------------------|
 145 |               file creation date                   | Creation date of the file
 146 |----------------------------------------------------|
 147 |               number of packages                   | Counted packages which will be transferred in the data packages
 148 |----------------------------------------------------|
 149 |                      FLER                          | Package flag
 150 |----------------------------------------------------|
 151 \endcode
 152 If the file doesn't exist, the conent of the error package is a little bit different:
 153 \code
 154 |----------------------------------------------------|
 155 |                      FLER                          | Package flag
 156 |----------------------------------------------------|
 157 |                   error code                       | see error codes above
 158 |----------------------------------------------------|
 159 |                linux error code                    | standard linux error code
 160 |----------------------------------------------------|
 161 |                    filename                        | Use the absolute filepath to the file
 162 |----------------------------------------------------|
 163 |                      FLER                          | Package flag
 164 |----------------------------------------------------|
 165 \endcode
 166
 167 \section Using Using DLT Filetransfer
 168 There are two ways to use the filetransfer
 169         \li Automatic filetransfer in one step
 170         \li Header, data and end package order handeld by the user
 171
 172 \subsection Automatic Automatic
 173 Call
 174         \li dlt_user_log_file_complete
 175
 176 The method needs the following arguments:
 177         \li fileContext -> Context for logging the file to dlt
 178         \li filename -> Use the absolute file path to the file
 179         \li deleteFlag -> Flag if the file will be deleted after transfer. 1->delete, 0->notDelete
 180         \li timeout -> Deprecated.
 181
 182 The order of the packages is to send at first the header, then one or more data packages (depends on the filesize) and in the end the end package.
 183 The advantage of this method is, that you must not handle the package ordering by your own.
 184
 185 Within dlt_user_log_file_complete the free space of the user buffer will be checked. If the free space of the user buffer < 50% then the
 186 actual package won't be transferred and a timeout will be executed.
 187
 188 If the daemon crashes and the user buffer is full -> the automatic method is in an endless loop.
 189
 190 \subsection Manual Manual
 191 Manual starting filetransfer with the following commands:
 192         \li dlt_user_log_file_head | Transfers only the header of the file
 193         \li dlt_user_log_file_data | Transfers only one single package of a file
 194     \li dlt_user_log_file_end | Tranfers only the end of the file
 195
 196 This ordering is very important, so that you can save the transferred files to hard disk on client side with a dlt viewer plugin.
 197 The advantage of using several steps to transfer files by your own is, that you are very flexible to integrate the filetransfer
 198 in your code.
 199
 200 An other difference to the automatic method is, that only a timeout will be done. There is no check of the user buffer.
 201
 202 \subsection Important Important for integration
 203 You should care about blocking the main program when you intergrate filetransfer in your code.
 204 Maybe it's useful to extract the filetransfer in an extra thread.
 205 Another point is the filesize. The bigger the file is, the longer takes it to log the file to dlt.
 206
 207 \section Example Example dlt filetransfer
 208 For an example file transfer you can use
 209 \code
 210 Usage: dlt-example-filetransfer [options] <command>
 211 Filetransfer example with DLT Package Version: 2.2.0 , Package Revision: 1666, build on May 28 2011 02:18:19
 212
 213 Command:
 214 -f file      - File to transfer (absolute path)
 215 Options:
 216 -a apid      - Set application id to apid (default: FLTR)
 217 -c ctid      - Set context id to ctid (default: FLTR)
 218 -t ms        - Timeout between file packages in ms (minimum 20 ms)
 219 -d           - Flag to delete the file after the transfer (default: false)
 220 -i           - Flag to log file infos to DLT before transfer file (default: false)
 221 -h           - This help
 222 \endcode
 223
 224 \section Test Testing dlt filetransfer
 225 When you call "sudo make install", some automatic tests will be installed. Start the test using the following command from bash:
 226 \code
 227 dlt-test-filetransfer
 228 \endcode
 229 It's important that the dlt-filetransfer example files are installed in /usr/share/dlt-filetransfer which will be done automatically by using "sudo make install".
 230 \subsection testFile1Run1
 231 Test the file transfer with the condition that the transferred file is smaller as the file transfer buffer using dlt_user_log_file_complete.
 232 \subsection testFile1Run2
 233 Test the file transfer with the condition that the transferred file is smaller as the file transfer buffer using single package transfer
 234 \subsection testFile2Run1
 235 Test the file transfer with the condition that the transferred file is bigger as the file transfer buffer using dlt_user_log_file_complete.
 236 \subsection testFile2Run2
 237 Test the file transfer with the condition that the transferred file is bigger as the file transfer buffer using single package transfer
 238 \subsection testFile3Run1
 239 Test the file transfer with the condition that the transferred file does not exist using dlt_user_log_file_complete.
 240 \subsection testFile3Run2
 241 Test the file transfer with the condition that the transferred file does not exist using single package transfer
 242 \subsection testFile3Run3
 243 Test which logs some information about the file.
 244
 245
 246
 247
 248 \section Requirements Requirements
 249  \code
 250  automotive-dlt
 251  \endcode
 252  <hr>
 253
 254 \section Licence Licence
 255 Copyright 2011 - BMW AG, Christian Muck <christian.muck@bmw.de>
 256
 257 * */