Docs » Autodocs » card.resource » CopyTuple
CopyTuple -- Find/copy a credit card tuple.
success = CopyTuple( CardHandle, buffer, tuplecode, size );
d0 a1 a0 d1 d0
BOOL CopyTuple( struct CardHandle *, UBYTE *, ULONG, ULONG );
This function scans credit-card memory for a tuple, and
if found, copies it into a supplied buffer. The entire
tuple (including the tuple code, and link) are copied to
the supplied buffer. The number of bytes copied to the
buffer will be 2 bytes, plus the argument "size", or the
value in the tuple LINK field (whichever is SMALLER).
The software calling this function is responsible for
examining the copy of the tuple (e.g., recognition of
fields, recognition of stop bytes, etc. within the tuple).
This function does the best job it can to find a tuple
in attribute, or common memory. It follows tuple chains,
and skips odd bytes in attribute memory.
This function monitors for credit-card removal while reading data.
If the credit-card is removed while a byte is being read, it will
stop searching, and return FALSE.
This function does not protect against another task writing
to credit-card memory while data is being read. The device
is responsible for single-threading reads/writes to the
credit card as needed.
This function can be used to find multiple tuple codes; this
is a very rare case, so the mechanism provided for doing so is
unusual. See INPUTS below for more information.
This function does not read bytes within the body of any tuples
except for the tuple you want copied, and the basic compatibility
tuples this function understands (see list below).
On some machines this function may slow down memory access
speed while reading the tuple chain. This is done to prevent
potential problems on slow cards. By examining the CISTPL_DEVICE,
and CISTPL_DEVICE_A tuples, you can determine the best possible
memory access speed for the type of card inserted. Because memory
access speed may be slowed down, calls to this function should
The Card Information Structure must start with a CISTPL_DEVICE
tuple stored as the first tuple in attribute memory. If not,
this function will search for a CISTPL_LINKTARGET tuple
stored at byte 0 of common memory. Therefore it is possible
to store a CIS on cards which do not have any writeable
attribute memory, though this may cause problems for other
software implemented on other machines. For example, some
SRAM cards do not come with writeable attribute memory, and/or
some may have OPTIONAL EEPROM memory which may not have been
initialized by the card manufacturer. While it could be
argued that such cards do not conform to the PCMCIA PC Card
Standard, such cards are cheaper, and therefore likely to be
CardHandle - Same handle as that used when OwnCard() was
buffer - Pointer to a buffer where the tuple will be copied.
The buffer should be at least as large as "size" + 8 (see
use of "size" argument below). Therefore the minimum buffer
size is 8 bytes. See NOTES below.
tuplecode - The tuple code you want to search for. This is
a ULONG value. The upper 16 bits should be 0, or a number between
1-32K where a value of 0 means you want to find the first tuple
match, a value of 1 the second, etc. For example -
0x41 means find the FIRST tuple equal to $41.
((1<<16)|(0x41)) means find the SECOND tuple equal to $41.
((2<<16)|(0x41)) means find the THIRD tuple equal to $41.
size - The maximum number of bytes you want copied (not
including the tuple code, and link). The actual number
of bytes copied may be less than "size" if the tuple
link field is less than "size".
A size of 0 will result in only the tuple code, and
link being copied to your buffer if the tuple is found.
If you do not care how many bytes are copied, any unsigned
value of 255 or greater will do. In this case a maximum
of 257 bytes might be copied to your buffer (if the
tuple link field is the maximum of 255).
Other sizes are useful if you know the size of the tuple
you want copied, or you know there are active registers
stored within the tuple, and only want to copy a portion
of a tuple.
TRUE if the tuple was found, and copied, else FALSE.
This function may also return false if the CIS is believed
to be corrupt, or if the card is removed while reading the
This function can be called multiple times (adjusting the "size"OwnCard()
argument) to read a tuple of variable length, or unknown size.
Your supplied buffered is used by this function for working
storage - the contents of it will be modified even if this
function fails to find the tuple you want a copy of.
This function should NOT be used to find/copy tuples of type :
These tuples are automatically handled for you by this function.