note
	description: "[
		An interface for communicating with a medium which as HD44780 controller is attached to.
		
		At the time of writing this is either a IEEE 1284 parallel port (EPP or ECP 8-bit) or a USB.
	]"
	legal   : "See notice at end of class."
	status  : "See notice at end of class.";
	author  : "Paul Bates (paul.a.bates@gmail.com)"
	date    : "$Date$"
	revision: "$Revision$"

deferred class
	HD44780_COMM_CHANNEL_I [G -> PRT_CONNECTION]

feature {NONE} -- Initialization

	make (a_connection: like connection)
			-- Initialize a new comm channel using a parallel port connection
		require
			a_connection_attached: attached a_connection
			a_connection_is_interface_usable: a_connection.is_interface_usable
			a_connection_is_writable: a_connection.is_writable
		do
			connection := a_connection
		ensure
			connection_set: connection = a_connection
		end

feature {NONE} -- Access

	connection: G
			-- Connection to a port.

feature {HD44780_CONTROLLER} -- Status report

	is_writable: BOOLEAN
			-- Indicates if comm channel can be written to.
		do
			Result := connection.is_writable
		end

	is_readable: BOOLEAN
			-- Indicates if comm channel can be read from.
		do
			Result := connection.is_readable
		end

	is_4bit_channel: BOOLEAN
			-- Indicates if the communication channel transmits in 4 and not 8 bits.
		deferred
		end

	is_transaction_open: BOOLEAN
			-- Indicates if there is a transaction in process

feature {HD44780_CONTROLLER} -- Transaction

	frozen begin_transaction (a_instruction: BOOLEAN)
			-- Begins a communication transaction.
			--
			-- `a_instruction': When true an instruction transaction is being processed, otherwise it is a data transaction.
		require
			not_is_transaction_open: not is_transaction_open
			is_operable: is_writable or is_readable
		do
			is_transaction_open := True
			on_being_transaction (a_instruction)
		ensure
			is_transaction_open: is_transaction_open
		end

	frozen complete_transaction (a_instruction: BOOLEAN)
			-- Completes a communication transaction.
			--
			-- `a_instruction': When true an instruction transaction is being processed, otherwise it is a data transaction.
		require
			is_transaction_open: is_transaction_open
			is_operable: is_writable or is_readable
		do
			is_transaction_open := False
			on_complete_transaction (a_instruction)
		ensure
			not_is_transaction_open: not is_transaction_open
		end

feature {NONE} -- Transaction handlers

	on_being_transaction (a_instruction: BOOLEAN)
			-- Called when a transaction is about to start.
			--
			-- `a_instruction': When true an instruction transaction is being processed, otherwise it is a data transaction.
		require
			is_transaction_open: is_transaction_open
			is_operable: is_writable or is_readable
		deferred
		ensure
			is_transaction_open: is_transaction_open
		end

	on_complete_transaction (a_instruction: BOOLEAN)
			-- Called when a transaction has been completed.
			--
			-- `a_instruction': When true an instruction transaction is being processed, otherwise it is a data transaction.
		require
			not_is_transaction_open: not is_transaction_open
			is_operable: is_writable or is_readable
		deferred
		ensure
			not_is_transaction_open: not is_transaction_open
		end

feature {HD44780_CONTROLLER} -- Write operations

	send (a_data: NATURAL_8)
			-- Attempts to send a 8-bit instruction to a HD44780 controller
		require
			is_writable: is_writable
			is_transaction_open: is_transaction_open
		deferred
		end

feature {HD44780_CONTROLLER} -- Read operations

	retrieve: NATURAL_8
			-- Attempts to retrieve a 8-bit instruction from a HD44780 controller
		require
			is_readable: is_readable
			is_transaction_open: is_transaction_open
		deferred
		end

invariant
	connection_attached: attached connection

end