smartcard 0.3.1-x86-mswin32-60

data/BUILD

@@ -0,0 +1,65 @@
+= Builds are hard
++smartcard+ needs to talk to hardware (card readers), so it's bound to use a Ruby extension.
+This means C, and platform-specific building nightmares. Read below for details.
+
+= The build system
++smartcard+ uses {echoe}[http://blog.evanweaver.com/files/doc/fauna/echoe/] for builds. This
+automates most of the building and packaging work, and can even push the gem to rubyforge,
+with a bit of luck. Most used commands:
+	rake manifest # builds the manifest (do this after checking out)
+	rake package # builds the gem for your platform
+	rake mswin package # cross-builds the gem for Windows
+	rake test # builds the gem and runs the tests
+	rake docs # runs Rdoc to produce the docs
+
+On the other hand, you have to <tt>gem install echoe</tt> to be able to build anything.
+
+= Platform-specific information
+
+== OSX
+
+You need to install the Developer Tools to get gcc.
+
+Leopard includes a working PC/SC provider, as well as a good driver for CCID readers.
+Tiger's PC/SC implementation is broken and incomplete, so the Ruby extension code in +smartcard+
+has a few hacks to work around that (look for the <tt>RB_SMARTCARD_OSX_TIGER_HACK</tt> define.
+The following commands are broken / don't work:
+* Smartcard::PCSC::Context#is_valid (always returs +true+)
+* Smartcard::PCSC::Card#get_attribute (throws exception because it's not implemented)
+* Smartcard::PCSC::Card#set_attribute (throws exception because it's not implemented)
+* Smartcard::PCSC::Card#control (Tiger's API is broken, so the call will probably not work)
+
+The developer team doesn't support or test against ports of +gcc+ or +pcsclite+,
+but we success notifications are welcome.
+
+== Windows
+
+A lot of effort has been spent to make Windows builds as easy as possible.
++smartcard+ is currently built using a full edition of
+{Visual Studio 2005}[http://msdn.microsoft.com/vstudio/], but all sources
+indicate that {Visual C++ Express 2005}[http://www.microsoft.com/express/download/] works,
+as long as you also install a Windows SDK (you're on your own for that). Visual Studio 2008
+might work, but it hasn't been tested yet.
+
+A summary of the hacks that have been done to get Windows builds working:
+* removing the extension files from the gemspec at the "right time" so that +echoe+ compiles the extension, and the gem doesn't require re-compilation (see the +Rakefile+)
+* adding the compiled extension to the file list in the gemspec
+* adding code to <tt>extconf.rb</tt> to patch the +Makefile+ so a manifest is embedded in the extension dll (and ruby doesn't crash if it uses a different version of the C runtime)
+
+== Linux
+
++smartcard+ is developed (and tested) against the
+{MUSCLE project}[http://www.linuxnet.com/software.html]. If you go this route, you need to
+get at least the {pcsclite library}[http://pcsclite.alioth.debian.org/] and a driver.
++smartcard+ developers use the {CCID driver}[http://pcsclite.alioth.debian.org/], which
+works on most (new) readers.
+
+=== Ubuntu
+
+Installing the following packages (and their dependencies) gets you going on Ubuntu (tested on 7.10):
+* buildessentials
+* libccid
+* libpcsclite
+* libpcsclite-dev
+* pcscd
+* pcsc-tools

data/CHANGELOG

@@ -0,0 +1,29 @@
+v0.3.1. Fixed documentation for the new PcscException class.
+
+v0.3.0. Added PcscException class used to wrap PC/SC exceptions.
+
+v0.2.3. Fixed minor bug in error string for PCSC::Card.transmit 
+
+v0.2.2. Fixed APDU exchange bugs on Windows
+	Restructured PCSC::IoRequest to allow PCI_ consts
+	Added PCI_ consts
+	Changed test suite to reflect proper way to do transmits
+
+v0.2.1. Added OSX Tiger support
+	Many workarounds for Tiger's buggy/incomplete PC/SC.
+	Small bugfixes for PC/SC status constants.
+
+v0.2.0. Added automatic builds
+	Rakefile for auto builds using echoe
+	extconf.rb: hack to fix Windows makefiles 
+
+v0.1.2. Added Windows compatibility
+	*.c: restructured code so VC2005 likes it
+	(variable declarations before function body)
+	docs: license, readme, and what the gem is
+
+v0.1.1. Added support for Ubuntu 7.10
+	ext/smartcard_pcsc/extconf.rb: better header
+	detection
+
+v0.1.0. Initial release for OSX Leopard

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2007 Massachusetts Institute of Technology
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Manifest

@@ -0,0 +1,23 @@
+BUILD
+CHANGELOG
+ext/smartcard_pcsc/extconf.rb
+ext/smartcard_pcsc/pcsc.h
+ext/smartcard_pcsc/pcsc_card.c
+ext/smartcard_pcsc/pcsc_constants.c
+ext/smartcard_pcsc/pcsc_context.c
+ext/smartcard_pcsc/pcsc_exception.c
+ext/smartcard_pcsc/pcsc_io_request.c
+ext/smartcard_pcsc/pcsc_main.c
+ext/smartcard_pcsc/pcsc_multi_strings.c
+ext/smartcard_pcsc/pcsc_namespace.c
+ext/smartcard_pcsc/pcsc_reader_states.c
+ext/smartcard_pcsc/pcsc_surrogate_reader.h
+ext/smartcard_pcsc/pcsc_surrogate_wintypes.h
+lib/smartcard/pcsc_exception.rb
+lib/smartcard.rb
+LICENSE
+Manifest
+README
+test/test_containers.rb
+test/test_smoke.rb
+tests/ts_pcsc_ext.rb

data/README

@@ -0,0 +1,32 @@
++smartcard+ aims to become the standard support library for smart-card development on ruby.
+Right now, the project offers a PC/SC binding that is working on ruby 1.8, under
+Linux, OSX, and Windows. Future plans include a high level abstraction for the PC/SC binding 
+(plus any other bindings people need), and an interface for Java cards.
+
+= Installation
+
+	gem install smartcard
+Windows:: Select the <tt>win32</tt> gem.
+OSX:: Install the Developer Tools to get +gcc+. Requires Tiger or Leopard.
+UNIX:: You need a PC/SC provider. See the {BUILD file}[link://files/BUILD.html] for details. The file also contains package lists for popular distributions.
+
+= Documentation
+
+The documentation you see was generated with RDoc. If you install the +smartcard+ gem, you should be
+able to use ri to see the documentation. If you're using the SVN version, you can <tt>rake doc</tt> to build
+the HTML documentation yourself.
+
+= License
+
++smartcard+ is released under the MIT license. This means you're free to do whatever you want
+with it. However, it'd be nice to let the developers know if you plan to include this in a
+distribution (bragging rights are always good). The {LICENSE file}[link://files/LICENSE.html]
+has the license in legalese.
+
+= Acknowledgements
+
++smartcard+ is developed by Victor Costan while working as a Research Assistant for MIT, under
+{Prof. Srini Devadas}[http://people.csail.mit.edu/devadas/], in the
+{Trusted Computing group}[http://projects.csail.mit.edu/tc/].
+The work is funded by a grant from {Quanta Computer Inc}[http://www.quanta.com.tw], under the
+{T-Party Project}[http://projects.csail.mit.edu/tparty/].

data/ext/smartcard_pcsc/extconf.rb

@@ -0,0 +1,70 @@
+require 'mkmf'
+
+$CFLAGS ||= ''
+$LDFLAGS ||= ''
+
+pcsc_defines = []
+
+if RUBY_PLATFORM =~ /darwin/
+  $LDFLAGS += ' -framework PCSC'
+  darwin_version = `uname -r`
+  if darwin_version =~ /^8./
+    pcsc_defines.push 'RB_SMARTCARD_OSX_TIGER_HACK'
+  end
+elsif RUBY_PLATFORM =~ /win/
+  
+  have_library('winscard')
+  pcsc_defines << 'PCSC_SURROGATE_SCARD_IS_VALID_CONTEXT' unless have_library('winscard', 'SCardIsValidContext')
+else
+  # pcsclite is retarded and uses stuff like '#include <wintypes.h>'
+  $CFLAGS += ' -I /usr/include/PCSC -I /usr/local/include/PCSC'
+  have_library('pcsclite')
+end
+
+pcsc_headers = []
+['wintypes.h', 'reader.h', 'winscard.h', 'pcsclite.h'].each do |header|
+  ['', 'PCSC/', './pcsc_surrogate_'].each do |path_prefix|
+    if have_header(path_prefix + header)
+      pcsc_headers.push((path_prefix[0,1] == '.') ? "\"#{path_prefix + header}\"" : "<#{path_prefix + header}>")
+      break
+    end
+  end
+end
+
+File.open('pcsc_autogen.h', 'w') do |f|
+  pcsc_defines.each { |d| f.write "\#define #{d}\n" }
+  pcsc_headers.each { |h| f.write "\#include #{h}\n" }
+end 
+
+create_makefile('smartcard/pcsc')
+
+def win32_hack(mf_name)
+  # get the version of MSVC
+  Kernel.system `cl 2> msvc_version.txt`
+  msvc_logo = File.open('msvc_version.txt') { |f| f.read }
+  print msvc_logo
+  File.delete 'msvc_version.txt'
+  if msvc_logo =~ /Optimizing Compiler Version (\d+)/
+    msvc_ver = $1.to_i  
+    # for MSVC 6.0, no manifest BS is needed -- straight-up compilation is good
+    return if msvc_ver == 12
+  end
+    
+  # evil, evil, evil -- hack the makefile to embed the manifest in the extension dll
+  make_contents = File.open(mf_name, 'r') { |f| f.read }
+  make_rules = make_contents.split(/(\n|\r)(\n|\r)+/)
+  new_make_rules = make_rules.map do |rule|
+    if rule =~ /^\$\(DLLIB\)\:/
+      rule + "\n\tmt.exe -manifest $(@).manifest -outputresource:$(@);2"
+    else
+      rule
+    end
+  end
+  File.open(mf_name, 'w') { |f| f.write new_make_rules.join("\n\n")}
+end
+
+case RUBY_PLATFORM
+when /darwin/
+when /win/
+  win32_hack 'Makefile'
+end

data/ext/smartcard_pcsc/pcsc.h

@@ -0,0 +1,52 @@
+/* Ruby extension API. */
+#include <ruby.h>
+/* Generated by 'extconf.rb' to point to the PC/SC header. */
+#include "pcsc_autogen.h"
+
+/* Entrypoint into the Ruby extension. */
+void Init_pcsc();
+
+/* Namespace structure. */
+extern VALUE mSmartcard; /* Smartcard module / namespace */
+extern VALUE mPcsc; /* Smartcard::PCSC module / namespace */
+
+/* Class Smartcard::PCSC::ReaderStates */
+extern VALUE cPcscReaderStates;
+void Init_PCSC_ReaderStates();
+int _PCSC_ReaderStates_lowlevel_get(VALUE rbReaderStates, SCARD_READERSTATE **reader_states, size_t *reader_states_count);
+
+/* Class Smartcard::PCSC::IoRequest */
+extern VALUE cPcscIoRequest;
+void Init_PCSC_IoRequest();
+int _PCSC_IoRequest_lowlevel_get(VALUE rbIoRequest, SCARD_IO_REQUEST **io_request);
+VALUE _PCSC_IoRequest_lowlevel_new(const SCARD_IO_REQUEST *io_request);
+
+/* Class Smartcard::PCSC::Context */
+extern VALUE cPcscContext;
+void Init_PCSC_Context();
+int _PCSC_Context_lowlevel_get(VALUE rbContext, SCARDCONTEXT *pcsc_context);
+
+/* Class Smartcard::PCSC::Card */
+extern VALUE cPcscCard;
+void Init_PCSC_Card();
+int _PCSC_Card_lowlevel_get(VALUE rbCard, SCARDHANDLE *card_handle);
+
+/* Class Smartcard::PCSC::Exception */
+extern VALUE ePcscException;
+void Init_PCSC_Exception();
+void _PCSC_Exception_raise(DWORD pcsc_error, char *pcsc_function);
+
+/* Constants in Smartcard::PCSC */
+void Init_PCSC_Consts();
+
+/* Multi-string (win32 abomination) tools. */
+VALUE PCSC_Internal_multistring_to_ruby_array(char *mstr, size_t mstr_len);
+int PCSC_Internal_ruby_strings_to_multistring(VALUE rbStrings, char **strings);
+
+/* Messing up with constants that aren't uniformly defined. */
+#if !defined(MAX_ATR_SIZE)
+#define MAX_ATR_SIZE 32
+#endif
+#if !defined(SCARD_PROTOCOL_ANY)
+#define SCARD_PROTOCOL_ANY (SCARD_PROTOCOL_T0 | SCARD_PROTOCOL_T1)
+#endif

data/ext/smartcard_pcsc/pcsc_card.c

@@ -0,0 +1,492 @@
+#include "pcsc.h"
+
+VALUE cPcscCard;
+
+/* Wraps a SCARDHANDLE, tracking whether it was released or not, together with the last error that occured on it. */
+struct SCardHandleEx {
+	SCARDHANDLE card_handle;
+	DWORD pcsc_error;
+	int released;
+};
+
+/* Custom free for Smartcard::PCSC::Card. Releases the card handle via a disconnect if that was not already done. */
+static void PCSC_Card_free(struct SCardHandleEx *_card) {
+	if(_card != NULL) {
+		if(!_card->released)
+			SCardDisconnect(_card->card_handle, SCARD_LEAVE_CARD);
+		xfree(_card);
+	}
+}
+
+/* Custom allocation for Smartcard::PCSC::Card. Wraps a SCardHandleEx. */
+static VALUE PCSC_Card_alloc(VALUE klass) {
+	struct SCardHandleEx *card;
+	
+	VALUE rbCard = Data_Make_Struct(klass, struct SCardHandleEx, NULL, PCSC_Card_free, card);
+	card->pcsc_error = SCARD_S_SUCCESS;
+	card->released = 1;
+	return rbCard;
+}
+
+/* :Document-method: new
+ * call-seq:
+ *      new(context, reader_name, share_mode, preferred_protocols) --> card
+ * 
+ * Establishes a connection to the card in the reader whose friendly name is +reader_name+.
+ * The first connection will power up and perform a reset on the card.
+ * Wraps _SCardConnect_ in PC/SC.
+ * 
+ * +context+:: the Smartcard::PCSC::Context to use to connect to the PC/SC resource manager
+ * +reader_name+:: friendly name of the reader to connect to; get using Smartcard::PCSC::Context#list_readers 
+ * +share_mode+:: whether a shared or exclusive lock will be requested on the reader; use one of the Smartcard::PCSC::SHARE_ constants 
+ * +preferred_protocols+:: desired protocol; use one of the Smartcard::PCSC::PROTOCOL_ constants
+ */
+static VALUE PCSC_Card_initialize(VALUE self, VALUE rbContext, VALUE rbReaderName, VALUE rbShareMode, VALUE rbPreferredProtocols) {
+	struct SCardHandleEx *card;
+	SCARDCONTEXT context;
+	VALUE rbFinalReaderName;
+	DWORD share_mode, preferred_protocols, active_protocol;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	
+	if(_PCSC_Context_lowlevel_get(rbContext, &context) == 0) {
+		rb_raise(rb_eArgError, "first argument is not a Context instance");
+		return self;
+	}
+	
+	rbFinalReaderName = rb_check_string_type(rbReaderName);
+	if(NIL_P(rbFinalReaderName)) {
+		rb_raise(rb_eArgError, "second argument (should be reader name) does not convert to a String");
+		return self;
+	}
+	
+	share_mode = NUM2UINT(rbShareMode);
+	preferred_protocols = NUM2UINT(rbPreferredProtocols);
+	
+	card->pcsc_error = SCardConnect(context, RSTRING(rbFinalReaderName)->ptr, share_mode, preferred_protocols, &card->card_handle, &active_protocol);	
+	if(card->pcsc_error != SCARD_S_SUCCESS)
+		_PCSC_Exception_raise(card->pcsc_error, "SCardConnect");
+	else
+		card->released = 0;
+	return self;
+}
+
+/* :Document-method: reconnect
+ * call-seq:
+ *      card.reconnect(share_mode, preferred_protocols, initialization) --> self
+ * 
+ * Reestablishes a connection to a reader that was previously connected to using Card#new.
+ * Wraps _SCardReconnect_ in PC/SC.
+ * 
+ * +share_mode+:: whether a shared or exclusive lock will be requested on the reader; use one of the Smartcard::PCSC::SHARE_ constants 
+ * +preferred_protocols+:: desired protocol; use one of the Smartcard::PCSC::PROTOCOL_ constants
+ * +initialization+:: action to be taken on the card inside the reader; use one of the Smartcard::PCSC::INITIALIZE_ constants
+ */
+static VALUE PCSC_Card_reconnect(VALUE self, VALUE rbShareMode, VALUE rbPreferredProtocols, VALUE rbInitialization) {
+	struct SCardHandleEx *card;
+	DWORD share_mode, preferred_protocols, initialization, active_protocol;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return self;
+
+	share_mode = NUM2UINT(rbShareMode);
+	preferred_protocols = NUM2UINT(rbPreferredProtocols);
+	initialization = NUM2UINT(rbInitialization);
+	
+	card->pcsc_error = SCardReconnect(card->card_handle, share_mode, preferred_protocols, initialization, &active_protocol);
+	if(card->pcsc_error != SCARD_S_SUCCESS)
+		_PCSC_Exception_raise(card->pcsc_error, "SCardReconnect");		
+
+	return self;
+}
+
+/* :Document-method: disconnect
+ * call-seq:
+ *      context.disconnect(disposition) --> self
+ * 
+ * Terminates the connection made using Card#new. The Card object is invalid afterwards.
+ * Wraps _SCardDisconnect_ in PC/SC.
+ * 
+ * +disposition+:: action to be taken on the card inside the reader; use one of the Smartcard::PCSC::DISPOSITION_ constants
+ */
+static VALUE PCSC_Card_disconnect(VALUE self, VALUE rbDisposition) {
+	struct SCardHandleEx *card;
+	DWORD disposition;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return self;
+
+	disposition = NUM2UINT(rbDisposition);
+	if(!card->released) {
+		card->pcsc_error = SCardDisconnect(card->card_handle, disposition);		
+		card->released = 1;
+		if(card->pcsc_error != SCARD_S_SUCCESS)
+			_PCSC_Exception_raise(card->pcsc_error, "SCardDisconnect");		
+	}
+	return self;
+}
+
+/* :Document-method: begin_transaction
+ * call-seq:
+ *      card.begin_transaction() --> self
+ * 
+ * Establishes a temporary exclusive access mode for doing a series of commands or transaction. 
+ * Wraps _SCardBeginTransaction_ in PC/SC.
+ */
+static VALUE PCSC_Card_begin_transaction(VALUE self) {
+	struct SCardHandleEx *card;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return self;
+	
+	card->pcsc_error = SCardBeginTransaction(card->card_handle);
+	if(card->pcsc_error != SCARD_S_SUCCESS)
+		_PCSC_Exception_raise(card->pcsc_error, "SCardBeginTransaction");		
+	return self;
+}
+
+/* :Document-method: end_transaction
+ * call-seq:
+ *      context.end_transaction(disposition) --> attribute_value
+ * 
+ * Ends a previously begun transaction. The calling application must be the owner of the previously begun transaction or an error will occur. 
+ * Wraps _SCardEndTransaction_ in PC/SC.
+ * 
+ * +disposition+:: action to be taken on the card inside the reader; use one of the Smartcard::PCSC::DISPOSITION_ constants
+ */
+static VALUE PCSC_Card_end_transaction(VALUE self, VALUE rbDisposition) {
+	struct SCardHandleEx *card;
+	DWORD disposition;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return self;
+	
+	disposition = NUM2UINT(rbDisposition);
+	card->pcsc_error = SCardEndTransaction(card->card_handle, disposition);
+	if(card->pcsc_error != SCARD_S_SUCCESS)
+		_PCSC_Exception_raise(card->pcsc_error, "SCardEndTransaction");		
+	return self;
+}
+
+/* :Document-method: get_attribute
+ * call-seq:
+ *      card.get_attribute(attribute_id) --> attribute_value
+ * 
+ * Reads the value of an attribute from the interface driver.
+ * Remember that the IFD may not implement some of the attributes specified in Smartcard::PCSC, and it may implement some attributes that
+ * are not included in Smartcard::PCSC.
+ * Wraps _SCardGetAttrib_ in PC/SC.
+ * 
+ * The returned value has the bytes in the attribute, wrapped in a string. (don't complain, it's a low-level API)
+ * 
+ * +attribute_id+:: identifies the attribute to be read; use one of the Smartcard::PCSC::ATTR_ constants
+ */
+static VALUE PCSC_Card_get_attribute(VALUE self, VALUE rbAttributeId) {
+	struct SCardHandleEx *card;
+	char *attribute_buffer;
+	DWORD attribute_id, attribute_length;
+	VALUE rbAttribute;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return Qnil;
+	
+	attribute_id = NUM2UINT(rbAttributeId);
+	attribute_length;
+#if defined(RB_SMARTCARD_OSX_TIGER_HACK)
+	card->pcsc_error = SCARD_F_INTERNAL_ERROR;
+	rb_raise(rb_eRuntimeError, "SCardSetAttrib: not implemented in OSX Tiger");
+#else
+	card->pcsc_error = SCardGetAttrib(card->card_handle, attribute_id, NULL, &attribute_length);
+	if(card->pcsc_error == SCARD_S_SUCCESS) {
+		attribute_buffer = ALLOC_N(char, attribute_length);
+		if(attribute_buffer != NULL) {
+			card->pcsc_error = SCardGetAttrib(card->card_handle, attribute_id, (LPSTR)attribute_buffer, &attribute_length);
+			if(card->pcsc_error == SCARD_S_SUCCESS) {
+				rbAttribute = rb_str_new(attribute_buffer, attribute_length);
+				xfree(attribute_buffer);
+				return rbAttribute;
+			}
+		}
+	}
+	if(card->pcsc_error != SCARD_S_SUCCESS)
+		_PCSC_Exception_raise(card->pcsc_error, "SCardGetAttrib");		
+#endif
+	return Qnil;
+}
+
+/* :Document-method: set_attribute
+ * call-seq:
+ *      context.set_attribute(attribute_id, attribute_value) --> self
+ * 
+ * Sets the value of an attribute in the interface driver.
+ * Remember that the IFD may not implement some of the attributes specified in Smartcard::PCSC, and it may implement some attributes that
+ * are not included in Smartcard::PCSC.
+ * Wraps _SCardSetAttrib_ in PC/SC.
+ * 
+ * +attribute_id+:: identifies the attribute to be set; use one of the Smartcard::PCSC::ATTR_ constants
+ * +attribute_value+:: the value to be assigned to the attribute; wrap the bytes in a string-like object (low-level API, remember?)
+ */
+static VALUE PCSC_Card_set_attribute(VALUE self, VALUE rbAttributeId, VALUE rbAttributeValue) {
+	struct SCardHandleEx *card;
+	DWORD attribute_id;
+	VALUE rbFinalAttributeValue;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return self;
+	
+	attribute_id = NUM2UINT(rbAttributeId);
+
+	rbFinalAttributeValue = rb_check_string_type(rbAttributeValue);
+	if(NIL_P(rbFinalAttributeValue)) {
+		rb_raise(rb_eArgError, "second argument (attribute buffer) does not convert to a String");
+		return self;
+	}
+
+#if defined(RB_SMARTCARD_OSX_TIGER_HACK)
+	card->pcsc_error = SCARD_F_INTERNAL_ERROR;
+	rb_raise(rb_eRuntimeError, "SCardSetAttrib: not implemented in OSX Tiger");
+#else
+	card->pcsc_error = SCardSetAttrib(card->card_handle, attribute_id, (LPSTR)RSTRING(rbFinalAttributeValue)->ptr, RSTRING(rbFinalAttributeValue)->len);
+	if(card->pcsc_error != SCARD_S_SUCCESS)
+		_PCSC_Exception_raise(card->pcsc_error, "SCardSetAttrib");		
+#endif
+	return self;
+}
+
+/* :Document-method: transmit
+ * call-seq:
+ *      card.transmit(send_data, send_io_request, recv_io_request) --> recv_data
+ * 
+ * Sends an APDU to the smart card, and returns the card's response to the APDU.
+ * Wraps _SCardTransmit_ in PC/SC.
+ * 
+ * The bytes in the card's response are returned wrapped in a string. (don't complain, it's a low-level API)
+ * 
+ * +send_data+:: the APDU to be send to the card; wrap the bytes in a string-like object (low-level API, remember?)
+ * +send_io_request+:: Smartcard::PCSC::IoRequest instance indicating the send protocol; you should use one of the Smartcard::PCSC::IOREQUEST_ constants
+ * +recv_io_request+:: Smartcard::PCSC::IoRequest instance receving information about the recv protocol; you can use the result of Smartcard::PCSC::IoRequest#new
+ */
+static VALUE PCSC_Card_transmit(VALUE self, VALUE rbSendData, VALUE rbSendIoRequest, VALUE rbRecvIoRequest) {
+	struct SCardHandleEx *card;
+	VALUE rbFinalSendData, rbRecvData;
+	SCARD_IO_REQUEST *send_io_request, *recv_io_request;
+	char *recv_buffer;
+	DWORD recv_length;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return Qnil;
+	
+	rbFinalSendData = rb_check_string_type(rbSendData);
+	if(NIL_P(rbFinalSendData)) {
+		rb_raise(rb_eArgError, "first argument (send buffer) does not convert to a String");
+		return Qnil;
+	}
+	
+	if(_PCSC_IoRequest_lowlevel_get(rbSendIoRequest, &send_io_request) == 0) {
+		rb_raise(rb_eArgError, "second argument (send io request) is not an IoRequest instance");
+		return Qnil;	
+	}	
+	if(_PCSC_IoRequest_lowlevel_get(rbRecvIoRequest, &recv_io_request) == 0) {
+		rb_raise(rb_eArgError, "third argument (recv io request) is not an IoRequest instance");
+		return Qnil;	
+	}
+	
+#if defined(PCSCLITE_MAX_MESSAGE_SIZE)
+	recv_length = PCSCLITE_MAX_MESSAGE_SIZE;
+#elif defined(MAX_BUFFER_SIZE_EXTENDED)
+	recv_length = MAX_BUFFER_SIZE_EXTENDED;
+#else
+	recv_length = 65536;
+#endif
+	recv_buffer = ALLOC_N(char, recv_length);
+	if(recv_buffer == NULL) return Qnil;
+	
+	card->pcsc_error = SCardTransmit(card->card_handle, send_io_request,
+			(LPSTR)RSTRING(rbFinalSendData)->ptr, RSTRING(rbFinalSendData)->len,
+			recv_io_request, (LPSTR)recv_buffer, &recv_length);	
+	if(card->pcsc_error != SCARD_S_SUCCESS) {
+		xfree(recv_buffer);
+		_PCSC_Exception_raise(card->pcsc_error, "SCardTransmit");		
+		return Qnil;
+	}
+
+	rbRecvData = rb_str_new(recv_buffer, recv_length);
+	xfree(recv_buffer);
+	return rbRecvData;			
+}
+
+/* :Document-method: control
+ * call-seq:
+ *      card.control(control_code, send_data, max_recv_bytes) --> recv_data
+ * 
+ * Sends a command directly to the interface driver to be processed by the reader.
+ * Useful for creating client side reader drivers for functions like PIN pads, biometrics, or other smart card reader
+ * extensions that are not normally handled by PC/SC. 
+ * Wraps _SCardControl_ in PC/SC.
+ * 
+ * The bytes in the response are returned wrapped in a string. (don't complain, it's a low-level API)
+ * 
+ * +control_code+:: control code for the operation; it's an integer, and it's IFD-specific
+ * +send_data+:: the data bytes to be send to the driver; wrap the bytes in a string-like object (low-level API, remember?)
+ * +max_recv_bytes+:: the maximum number of bytes that can be received
+ * 
+ * In general, I tried to avoid having you specify receive buffer sizes. This is the only case where that is impossible to achieve,
+ * because there is no well-known maximum buffer size, and the _SCardControl_ call is not guaranteed to be idempotent, so it's not OK to
+ * re-issue it until the buffer size works out.
+ */
+static VALUE PCSC_Card_control(VALUE self, VALUE rbControlCode, VALUE rbSendData, VALUE rbMaxRecvBytes) {
+	struct SCardHandleEx *card;	
+	VALUE rbFinalSendData, rbRecvData;
+	char *recv_buffer;
+	DWORD control_code, recv_length;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return Qnil;
+	
+	rbFinalSendData = rb_check_string_type(rbSendData);
+	if(NIL_P(rbFinalSendData)) {
+		rb_raise(rb_eArgError, "second argument (send buffer) does not convert to a String");
+		return Qnil;
+	}
+	
+	control_code = NUM2UINT(rbControlCode);
+	recv_length = NUM2UINT(rbMaxRecvBytes);
+	recv_buffer = ALLOC_N(char, recv_length);
+	if(recv_buffer == NULL) return Qnil;
+		
+#if defined(RB_SMARTCARD_OSX_TIGER_HACK)
+	/* TODO: this will compile and run, but it won't do anything useful */
+	card->pcsc_error = SCardControl(card->card_handle,
+			(LPSTR)RSTRING(rbFinalSendData)->ptr, RSTRING(rbFinalSendData)->len,
+			recv_buffer, &recv_length);
+#else
+	card->pcsc_error = SCardControl(card->card_handle, control_code,
+			(LPSTR)RSTRING(rbFinalSendData)->ptr, RSTRING(rbFinalSendData)->len,
+			recv_buffer, recv_length, &recv_length);
+#endif
+	if(card->pcsc_error != SCARD_S_SUCCESS) {
+		xfree(recv_buffer);
+		_PCSC_Exception_raise(card->pcsc_error, "SCardControl");		
+		return Qnil;
+	}
+
+	rbRecvData = rb_str_new(recv_buffer, recv_length);
+	xfree(recv_buffer);
+	return rbRecvData;			
+}
+
+static VALUE _rbStateKey, _rbProtocolKey, _rbAtrKey, _rbReaderNamesKey;
+
+/* :Document-method: status
+ * call-seq:
+ *      card.status() --> card_status
+ * 
+ * Retrieves the current status of the smartcard, and packages it up in a nice hash for you.
+ * Wraps _SCardStatus_ in PC/SC.
+ * 
+ * The response hash contains the following keys:
+ * <tt>:state</tt> :: reader/card status; bitfield, with bits defined as Smartcard::PCSC::STATUS_ constants
+ * <tt>:protocol</tt> :: the protocol established with the card; check against Smartcard::PCSC::PROTOCOL_ constants
+ * <tt>:atr</tt> :: the card's ATR bytes, wrapped in a string
+ * <tt>:reader_names</tt> :: array of strings containing all the names of the reader containing the smartcard
+ */
+static VALUE PCSC_Card_status(VALUE self) {
+	struct SCardHandleEx *card;
+	char *atr_buffer, *reader_names_buffer;
+	DWORD atr_length, reader_names_length, state, protocol;
+	VALUE rbStateVal, rbProtocolVal, rbAtrVal, rbReaderNamesVal, rbReturnHash;
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return Qnil;
+
+	atr_length = MAX_ATR_SIZE;
+	atr_buffer = ALLOC_N(char, atr_length);	
+	reader_names_length = 4096;
+	reader_names_buffer = ALLOC_N(char, reader_names_length);
+	if(atr_buffer == NULL || reader_names_buffer == NULL) {
+		if(reader_names_buffer != NULL) xfree(reader_names_buffer);
+		if(atr_buffer != NULL) xfree(atr_buffer);
+		return Qnil;
+	}
+	
+	card->pcsc_error = SCardStatus(card->card_handle, reader_names_buffer, &reader_names_length, &state, &protocol, (LPSTR)atr_buffer, &atr_length);
+	if(card->pcsc_error != SCARD_S_SUCCESS) {
+		xfree(reader_names_buffer); xfree(atr_buffer);
+		_PCSC_Exception_raise(card->pcsc_error, "SCardStatus");		
+		return Qnil;
+	}
+	
+	rbStateVal = UINT2NUM(state);
+	rbProtocolVal = UINT2NUM(protocol);
+	rbAtrVal = rb_str_new(atr_buffer, atr_length);
+	rbReaderNamesVal = PCSC_Internal_multistring_to_ruby_array(reader_names_buffer, reader_names_length);
+	
+	rbReturnHash = rb_hash_new();
+	rb_hash_aset(rbReturnHash, _rbStateKey, rbStateVal);
+	rb_hash_aset(rbReturnHash, _rbProtocolKey, rbProtocolVal);
+	rb_hash_aset(rbReturnHash, _rbAtrKey, rbAtrVal);
+	rb_hash_aset(rbReturnHash, _rbReaderNamesKey, rbReaderNamesVal);
+	return rbReturnHash;
+}
+
+/* :Document-method: last_error
+ * call-seq:
+ *      card.last_error() --> last_error
+ * 
+ * The error code returned by the last PC/SC call. Useful for recovering from exceptions.
+ * 
+ * The returned code is a number, and should be one of the Smartcard::PCSC::SCARD_ constants.
+ * The code indicating correct operation is Smartcard::PCSC::SCARD_S_SUCCESS.
+ */
+static VALUE PCSC_Card_last_error(VALUE self) {
+	struct SCardHandleEx *card;	
+	
+	Data_Get_Struct(self, struct SCardHandleEx, card);
+	if(card == NULL) return Qnil;
+
+	return UINT2NUM(card->pcsc_error);
+}
+
+#ifdef MAKE_RDOC_HAPPY
+	mSmartcard = rb_define_module("Smartcard");
+	mPcsc = rb_define_module_under(mSmartcard, "PCSC");
+#endif
+
+/* :Document-class: Smartcard::PCSC::Card
+ * Connects a smart-card in a PC/SC reader to the Ruby world.
+ * Wraps a _SCARDHANDLE_ structure.
+ */
+void Init_PCSC_Card() {
+	ID state_id, protocol_id, atr_id, reader_names_id;
+	
+	state_id = rb_intern("status"); _rbStateKey = ID2SYM(state_id);
+	protocol_id = rb_intern("protocol"); _rbProtocolKey = ID2SYM(protocol_id);
+	atr_id = rb_intern("atr"); _rbAtrKey = ID2SYM(atr_id);
+	reader_names_id = rb_intern("reader_names"); _rbReaderNamesKey = ID2SYM(reader_names_id);
+	
+	cPcscCard = rb_define_class_under(mPcsc, "Card", rb_cObject);
+	rb_define_alloc_func(cPcscCard, PCSC_Card_alloc);
+	rb_define_method(cPcscCard, "initialize", PCSC_Card_initialize, 4);
+	rb_define_method(cPcscCard, "disconnect", PCSC_Card_disconnect, 1);	
+	rb_define_method(cPcscCard, "reconnect", PCSC_Card_reconnect, 3);	
+	rb_define_method(cPcscCard, "begin_transaction", PCSC_Card_begin_transaction, 0);	
+	rb_define_method(cPcscCard, "end_transaction", PCSC_Card_end_transaction, 1);
+	rb_define_method(cPcscCard, "get_attribute", PCSC_Card_get_attribute, 1);	
+	rb_define_method(cPcscCard, "set_attribute", PCSC_Card_set_attribute, 2);
+	rb_define_method(cPcscCard, "transmit", PCSC_Card_transmit, 3);	
+	rb_define_method(cPcscCard, "control", PCSC_Card_control, 3);	
+	rb_define_method(cPcscCard, "status", PCSC_Card_status, 0);
+	rb_define_method(cPcscCard, "last_error", PCSC_Card_last_error, 0);
+}
+
+/* Retrieves the SCARDHANDLE wrapped into a Smartcard::PCSC::Card instance. */
+int _PCSC_Card_lowlevel_get(VALUE rbCard, SCARDHANDLE *card_handle) {
+	struct SCardHandleEx *card;	
+
+	if(TYPE(rbCard) != T_DATA || RDATA(rbCard)->dfree != (void (*)(void *))PCSC_Card_free)
+		return 0;
+	
+	Data_Get_Struct(rbCard, struct SCardHandleEx, card);
+	*card_handle = card->card_handle;
+	return 1;
+}