vcan_message_tag
================

Here is the definition::

  typedef enum
    { VCAN_READ_NOW=0, VCAN_READ=1, VCAN_READ_MANY=2, VCAN_READ_RTR=3,
      VCAN_WRITE=4, VCAN_SEND_RF=5, VCAN_GET_RFR=6, VCAN_WRITELATER=7,
      VCAN_QUEUE_READNOW=8, VCAN_QUEUE_READ=9, VCAN_WRITETIMED=10
    } vcan_message_tag;


This data type defines message-tag types for a vcan-request. Only the
vcan_request`` - structure contains a tag-field of this type. Requests are
driver-structures that are used to read or write to certain CAN objects.
Each message-tag corresponds to a single driver-function that is called in
the vcan-driver.

VCAN_READ_NOW
  This is the read-now driver-function. It reads data from a CAN object (a
  read-object) without waiting. This function can only be used when the
  system-function ``read`` is called.

VCAN_READ
  This is the read driver-function. It reads data from a CAN object (a
  read-object) but waits for new data to arrive, if it does not find new
  data at once. This function can only be used when the system-function
  ``read`` is called.

VCAN_READ_MANY
  This is the read-many driver-function. It reads data from one of several
  CAN objects (all read-objects), but waits for new data to arrive, if it
  does not find any new data in one of the objects. This function can only
  be used when the system-function read`` is called.

VCAN_READ_RTR
  This is the read-rtr driver-function. It reads data from a CAN object (a
  remote-read-object) using the remote-transmission mechanism. This function
  can only be used when the system-function read`` is called.

VCAN_WRITE
  This is the write driver-function. It writes data to a CAN object (a
  write- or remote-write-object) and waits for the successful writing of the
  data in case of a non-remote object. This function can only be used when
  the system-function ``write`` is called.

VCAN_SEND_RF
  This is the send-rf driver-function. It sends a remote-request frame on a
  CAN object but does not wait for the reply of the other CAN device. The
  data, written from the other side, has to be read with the
  ``VCAN_GET_RFR`` - function. This function can only be used when the
  system-function ``write`` is called.

VCAN_GET_RFR
  This is the get-rfr driver-function. It reads data from a remote-read
  object but does not send the remote-request frame before that. This
  function should always be used in conjunction with the
  ``VCAN_SEND_RF``-function. This function can only be used when the
  system-function ``read`` is called.

VCAN_WRITELATER
  This is the write-later driver-function. It writes data to a CAN object (a
  write- or remote-write-object) but does not waits for the successful
  writing of the data. By this mechanism it is faster than ``VCAN_WRITE``
  but cannot detect a transmission-error immediately. A transmission-error
  can only be detected, when the next write on the same CAN object takes
  place. This function can only be used when the system-function ``write``
  is called.

VCAN_QUEUE_READNOW
  -- deprecated --

VCAN_QUEUE_READ
  This is the queue-read driver-function. It reads data from a CAN object (a
  read-object) that is defined as an event-object with a signal-parameter of
  1. An object defined that way uses a semaphore-mechanism to notify the
  user of an event.  VCAN_QUEUE_READ`` is similar to ``VCAN_READ``, it waits
  for new data and returns when new data arrives in one of the several
  signal-objects.  A difference to ``VCAN_READ`` is that the CAN-Id of the
  object is not given to ``VCAN_QUEUE_READ`` but is returned by
  ``VCAN_QUEUE_READ`` instead. This function can only be used when the
  system-function read`` is called.

VCAN_WRITETIMED
  This is the write-timed driver-function. It writes data to a CAN object
  (only a write-, *not* a remote-write-object) but does not wait for
  the successful writing of the data. This function is similar to the
  write-later (``VCAN_WRITELATER``) function but the user can specify a so
  called inhibit-time. When the time that has passed since the last write is
  smaller than the inhibit-time, the function fails and returns a
  ``VCAN_WAIT``-status. It also returns the remaining time that the user has
  to wait before he can write again to the CAN-object. Note that the inhibit
  time (of the type ``unsigned long``) is passed to the function by the
  ``ptr``-field of the ``vcan_request`` driver-call-structure.  This is a
  pointer that must point to a variable of the type ``unsigned long``.  This
  variable should contain the inhibit-time in microseconds before
  ``VCAN_WRITETIMED`` is called. When the ``VCAN_WAIT``-status is returned,
  the remaining time to wait (in microseconds) is written back to the
  variable.