[Contents] [Index] [Help] [Retrace] [Browse <] [Browse >]

	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
	be single-threaded.

	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"
	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.


[Back to Amiga Developer Docs]