visa.go

// Package visa implements a Go interface to the Virtual Instrument Software
// Architecture (VISA) Library.
//
// The VISA Specifications are available at IVI Foundation's website
// http://www.ivifoundation.org/specifications/
//
// IVI's Implementation of VISA Library (VISA Shared Components) for Windows
// is at http://www.ivifoundation.org/shared_components/
//
// Implementations of VISA Library are also supplied by other vendors:
//
// 1. National Instruments provides NI-VISA for Windows, Linux, and OS X,
// at http://www.ni.com/visa/
//
// 2. Agilent provides Agilent IO Libraries Suite for Windows, at
// http://www.agilent.com/find/iosuite
package visa

import (
	"fmt"
	"sync"
)

type ResourceManager uint32

type Session struct {
	sync.Mutex

	vi uint32
	rl sync.Mutex
	wl sync.Mutex
}

type Event struct {
	context   uint32
	eventType EventType
}

/*- Resource Manager Functions and Operations -------------------------------*/

// OpenDefaultRM returns a session to the Default Resource Manager resource.
//
// This function must be called before any VISA operations can be invoked. The first call to this function initializes the VISA system, including the Default Resource Manager resource, and also returns a session to that resource. Subsequent calls to this function return unique sessions to the same Default Resource Manager resource.
//
// Possible Errors:
//     WARN_CONFIG_NLOADED
//     ERROR_SYSTEM_ERROR
//     ERROR_ALLOC
//     ERROR_INV_SETUP
//     ERROR_LIBRARY_NFOUND
func OpenDefaultRM() (r ResourceManager, err error) {
	return openDefaultRM()
}

// FindRsrc queries a VISA system to locate the resources associated with a specified interface.
//
// TODO: describe the rules for expr
//
// Possible Errors:
//     ERROR_INV_OBJECT
//     ERROR_INV_EXPR
//     ERROR_RSRC_NFOUND
func (r ResourceManager) FindRsrc(expr string) (rsrcList []string, err error) {
	return r.findRsrc(expr)
}

// ParseRsrc parses a resource string to get the interface information.
//
// This operation parses a resource string to verify its validity. It should succeed for all strings returned by FindRsrc() and recognized by Open(). This operation is useful if you want to know what interface a given resource descriptor would use without actually opening a session to it.
//
// The values returned in intfType and intfNum correspond to the attributes ATTR_INTF_TYPE and ATTR_INTF_NUM. These values would be the same if a user opened that resource with Open() and queried the attributes with GetAttribute().
//
// Possible Errors:
//     ERROR_INV_OBJECT
//     ERROR_INV_RSRC_NAME
//     ERROR_RSRC_NFOUND
//     ERROR_ALLOC
//     ERROR_LIBRARY_NFOUND
//     ERROR_INTF_NUM_NCONFIG
func (r ResourceManager) ParseRsrc(rsrcName string) (intfType IntfType, intfNum int, err error) {
	ifType, ifNum, err := r.parseRsrc(rsrcName)
	return IntfType(ifType), int(ifNum), err
}

// ParseRsrcEx parses a resource string to get extended interface information.
//
// This operation parses a resource string to verify its validity. It should succeed for all strings returned by FindRsrc() and recognized by Open(). This operation is useful if you want to know what interface a given resource descriptor would use without actually opening a session to it.
//
// The values returned in intfType and intfNum correspond to the attributes ATTR_INTF_TYPE and ATTR_INTF_NUM. These values would be the same if a user opened that resource with Open() and queried the attributes with GetAttribute().
//
// The value returned in unaliasedExpandedRsrcName should in most cases be identical to the VISA-defined canonical resource name. However, there may be cases where the canonical name includes information that the driver may not know until the resource has actually been opened. In these cases, the value returned in this parameter must be semantically similar.
//
// The value returned in aliasIfExists allows programmatic access to user-defined aliases.
//
// Possible Errors:
//     WARN_EXT_FUNC_NIMPL
//     ERROR_INV_OBJECT
//     ERROR_INV_RSRC_NAME
//     ERROR_RSRC_NFOUND
//     ERROR_ALLOC
//     ERROR_LIBRARY_NFOUND
//     ERROR_INTF_NUM_NCONFIG
func (r ResourceManager) ParseRsrcEx(rsrcName string) (intfType IntfType, intfNum int, rsrcClass string, expandedUnaliasedName string, aliasIfExists string, err error) {
	ifType, ifNum, rsrcClass, expandedUnaliasedName, aliasIfExists, err := r.parseRsrcEx(rsrcName)
	intfType = IntfType(ifType)
	intfNum = int(ifNum)
	return
}

// Open opens a session to the specified resource.
//
// The Open() operation opens a session to the specified resource. It returns a session identifier that can be used to call any other operations of that resource. The address string passed to Open() must uniquely identify a resource.
//
// For the parameter accessMode, the value EXCLUSIVE_LOCK is used to acquire an exclusive lock immediately upon opening a session; if a lock cannot be acquired, the session is closed and an error is returned. The value LOAD_CONFIG is used to configure attributes to values specified by some external configuration utility. Multiple access modes can be used simultaneously by specifying a bit-wise OR of the values other than NULL. NI-VISA currently supports LOAD_CONFIG only on Serial INSTR sessions.
//
// All resource strings returned by FindRsrc() will always be recognized by Open(). However, FindRsrc() will not necessarily return all strings that you can pass to ParseRsrc() or Open(). This is especially true for network and TCPIP resources.
//
// Possible Errors:
//     SUCCESS_DEV_NPRESENT
//     WARN_CONFIG_NLOADED
//     ERROR_INV_OBJECT
//     ERROR_INV_RSRC_NAME
//     ERROR_INV_ACC_MODE
//     ERROR_RSRC_NFOUND
//     ERROR_ALLOC
//     ERROR_RSRC_BUSY
//     ERROR_RSRC_LOCKED
//     ERROR_TMO
//     ERROR_LIBRARY_NFOUND
//     ERROR_INTF_NUM_NCONFIG
//     ERROR_MACHINE_NAVAIL
//     ERROR_NPERMISSION
func (r ResourceManager) Open(name string, mode AccessMode, timeout uint) (s *Session, err error) {
	return r.open(name, mode, timeout)
}

/*- Resource Template Operations --------------------------------------------*/

// Close the resource sessions.
//
// Possible Errors:
//     WARN_NULL_OBJECT
//     ERROR_INV_OBJECT
//     ERROR_CLOSING_FAILED
func (s *Session) Close() error {
	return s.close()
}

// SetAttribute sets the state of an attribute.
//
// Both WARN_NSUP_ATTR_STATE and ERROR_NSUP_ATTR_STATE indicate that the specified attribute state is not supported. A resource normally returns the error code ERROR_NSUP_ATTR_STATE when it cannot set a specified attribute state. The completion code WARN_NSUP_ATTR_STATE is intended to alert the application that although the specified optional attribute state is not supported, the application should not fail. One example is attempting to set an attribute value that would increase performance speeds. This is different than attempting to set an attribute value that specifies required but nonexistent hardware (such as specifying a VXI ECL trigger line when no hardware support exists) or a value that would change assumptions a resource might make about the way data is stored or formatted (such as byte order).
//
// Some attributes documented as being generally Read/Write may at times be Read Only. This is usually the case when an attribute configures how the VISA driver receives events of a given type, and the event type associated with that attribute is currently enabled. Under these circumstances, calling SetAttribute on that attribute returns ERROR_ATTR_READONLY.
//
// The error code ERROR_RSRC_LOCKED is returned only if the specified attribute is Read/Write and Global, and the resource is locked by another session.
//
// Possible Errors:
//     WARN_NSUP_ATTR_STATE
//     ERROR_INV_OBJECT
//     ERROR_NSUP_ATTR
//     ERROR_NSUP_ATTR_STATE
//     ERROR_ATTR_READONLY
//     ERROR_RSRC_LOCKED
func (s *Session) SetAttribute(attrID AttrID, attrState interface{}) error {
	switch attrID {
	// ViBoolean
	case
		ATTR_DMA_ALLOW_EN,
		ATTR_GPIB_READDR_EN,
		ATTR_GPIB_SYS_CNTRL_STATE,
		ATTR_GPIB_UNADDR_EN,
		ATTR_SEND_END_EN,
		ATTR_SUPPRESS_END_EN,
		ATTR_TERMCHAR_EN:
		switch value := attrState.(type) {
		case bool:
			if value {
				return s.setAttributeUint(attrID, 1)
			} else {
				return s.setAttributeUint(attrID, 0)
			}
		default:
			return fmt.Errorf("wrong type for attrState, expecting bool")
		}

	// ViInt16
	case
		ATTR_ASRL_DCD_STATE,
		ATTR_ASRL_DTR_STATE,
		ATTR_ASRL_RI_STATE,
		ATTR_ASRL_RTS_STATE,
		ATTR_GPIB_HS488_CBL_LEN,
		ATTR_TRIG_ID:
		switch value := attrState.(type) {
		case int:
			return s.setAttributeUint(attrID, uint(int16(value)))
		case int16:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting int or int16")
		}

	// ViUInt8
	case
		ATTR_ASRL_REPLACE_CHAR,
		ATTR_ASRL_XOFF_CHAR,
		ATTR_ASRL_XON_CHAR,
		ATTR_DEV_STATUS_BYTE,
		ATTR_TERMCHAR:
		switch value := attrState.(type) {
		case byte:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting byte")
		}

	// ViUInt16
	case
		ATTR_ASRL_DATA_BITS,
		ATTR_GPIB_PRIMARY_ADDR,
		ATTR_GPIB_SECONDARY_ADDR,
		ATTR_USB_MAX_INTR_SIZE:
		switch value := attrState.(type) {
		case int:
			return s.setAttributeUint(attrID, uint(uint16(value)))
		case uint16:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting int or uint16")
		}

	// ViUInt16
	case ATTR_ASRL_END_IN, ATTR_ASRL_END_OUT:
		switch value := attrState.(type) {
		case ASRL_End:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting ASRL_End")
		}

	// ViUInt16
	case ATTR_ASRL_FLOW_CNTRL:
		switch value := attrState.(type) {
		case ASRL_FlowControl:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting ASRL_FlowControl")
		}

	// ViUInt16
	case ATTR_ASRL_STOP_BITS:
		switch value := attrState.(type) {
		case ASRL_StopBits:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting ASRL_StopBits")
		}

	// ViUInt16
	case ATTR_ASRL_PARITY:
		switch value := attrState.(type) {
		case ASRL_Parity:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting ASRL_Parity")
		}

	// ViUInt16
	case ATTR_IO_PROT:
		switch value := attrState.(type) {
		case IOProt:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting IOProt")
		}

	// ViUInt32
	case
		ATTR_ASRL_BAUD,
		ATTR_TMO_VALUE:
		switch value := attrState.(type) {
		case int:
			return s.setAttributeUint(attrID, uint(uint32(value)))
		case uint32:
			return s.setAttributeUint(attrID, uint(value))
		default:
			return fmt.Errorf("wrong type for attrState, expecting int or uint32")
		}

	default:
		return ERROR_NSUP_ATTR
	}
}

// GetAttribute retrieves the state of an attribute.
//
// The output parameter attrState is of the type of the attribute actually being retrieved. For example, when retrieving an attribute that is defined as a bool, your application should pass a reference to a variable of type bool. Similarly, if the attribute is defined as being uint, your application should pass a reference to a variable of type uint.
//
// Possible Errors:
//     ERROR_INV_OBJECT
//     ERROR_NSUP_ATTR
func (s *Session) GetAttribute(attrID AttrID, attrState interface{}) error {
	switch attrID {
	// ViBoolean
	case
		ATTR_4882_COMPLIANT,
		ATTR_DMA_ALLOW_EN,
		ATTR_GPIB_CIC_STATE,
		ATTR_GPIB_READDR_EN,
		ATTR_GPIB_RECV_CIC_STATE,
		ATTR_GPIB_SYS_CNTRL_STATE,
		ATTR_GPIB_UNADDR_EN,
		ATTR_SEND_END_EN,
		ATTR_SUPPRESS_END_EN,
		ATTR_TERMCHAR_EN:
		if value, typeOK := attrState.(*bool); typeOK {
			return s.getAttributeBool(attrID, value)
		} else {
			return fmt.Errorf("wrong type for attrState, expecting *bool")
		}

	// ViUInt8
	case
		ATTR_ASRL_REPLACE_CHAR,
		ATTR_ASRL_XOFF_CHAR,
		ATTR_ASRL_XON_CHAR,
		ATTR_TERMCHAR,
		ATTR_DEV_STATUS_BYTE:
		if value, typeOK := attrState.(*uint8); typeOK {
			return s.getAttributeUint8(attrID, value)
		} else {
			return fmt.Errorf("wrong type for attrState, expecting *uint8")
		}

	// ViInt16
	case
		ATTR_ASRL_CTS_STATE,
		ATTR_ASRL_DCD_STATE,
		ATTR_ASRL_DSR_STATE,
		ATTR_ASRL_DTR_STATE,
		ATTR_ASRL_RI_STATE,
		ATTR_ASRL_RTS_STATE,
		ATTR_GPIB_ADDR_STATE,
		ATTR_GPIB_ATN_STATE,
		ATTR_GPIB_HS488_CBL_LEN,
		ATTR_GPIB_NDAC_STATE,
		ATTR_GPIB_REN_STATE,
		ATTR_GPIB_SRQ_STATE,
		ATTR_TRIG_ID,
		ATTR_USB_INTFC_NUM,
		ATTR_USB_PROTOCOL:
		if value, typeOK := attrState.(*int16); typeOK {
			return s.getAttributeInt16(attrID, value)
		} else {
			return fmt.Errorf("wrong type for attrState, expecting *int16")
		}

	// ViUInt16
	case
		ATTR_ASRL_DATA_BITS,
		ATTR_ASRL_END_IN,
		ATTR_ASRL_END_OUT,
		ATTR_ASRL_FLOW_CNTRL,
		ATTR_ASRL_PARITY,
		ATTR_ASRL_STOP_BITS,
		ATTR_GPIB_PRIMARY_ADDR,
		ATTR_GPIB_SECONDARY_ADDR,
		ATTR_INTF_NUM,
		ATTR_INTF_TYPE,
		ATTR_IO_PROT,
		ATTR_MANF_ID,
		ATTR_MODEL_CODE,
		ATTR_RSRC_MANF_ID,
		ATTR_USB_MAX_INTR_SIZE,
		ATTR_USB_RECV_INTR_SIZE:
		if value, typeOK := attrState.(*uint16); typeOK {
			return s.getAttributeUint16(attrID, value)
		} else {
			return fmt.Errorf("wrong type for attrState, expecting *uint16")
		}

	// ViUInt32
	case
		ATTR_ASRL_AVAIL_NUM,
		ATTR_ASRL_BAUD,
		ATTR_RSRC_IMPL_VERSION,
		ATTR_RSRC_SPEC_VERSION,
		ATTR_TMO_VALUE:
		if value, typeOK := attrState.(*uint32); typeOK {
			return s.getAttributeUint32(attrID, value)
		} else {
			return fmt.Errorf("wrong type for attrState, expecting *uint32")
		}

	// Platform dependent ViUInt32/ViUInt64
	case ATTR_RET_COUNT:
		if value, typeOK := attrState.(*uint); typeOK {
			return s.getAttributeUint(attrID, value)
		} else {
			panic("wrong type for attrValue passed in")
		}

	// ViString -> string
	case
		ATTR_INTF_INST_NAME,
		ATTR_MANF_NAME,
		ATTR_MODEL_NAME,
		ATTR_RSRC_CLASS,
		ATTR_RSRC_MANF_NAME,
		ATTR_TCPIP_ADDR,
		ATTR_TCPIP_HOSTNAME,
		ATTR_USB_SERIAL_NUM,
		ATTR_RSRC_NAME:
		if value, typeOK := attrState.(*string); typeOK {
			return s.getAttributeString(attrID, value)
		} else {
			panic("wrong type for attrValue passed in")
		}

	default:
		return ERROR_NSUP_ATTR
	}
}

/*- Basic I/O Operations ----------------------------------------------------*/

// Read reads data from device or interface synchronously.
//
// This operation synchronously transfers data. The data read is to be stored in the buffer represented by buf. This operation returns only when the transfer terminates. Only one synchronous read operation can occur at any one time.
//
// Possible Errors:
//     ERROR_INV_OBJECT
//     ERROR_NSUP_OPER
//     ERROR_RSRC_LOCKED
//     ERROR_TMO
//     ERROR_RAW_WR_PROT_VIOL
//     ERROR_RAW_RD_PROT_VIOL
//     ERROR_OUTP_PROT_VIOL
//     ERROR_BERR
//     ERROR_INV_SETUP
//     ERROR_NCIC
//     ERROR_NLISTENERS
//     ERROR_ASRL_PARITY
//     ERROR_ASRL_FRAMING
//     ERROR_ASRL_OVERRUN
//     ERROR_IO
//     ERROR_CONN_LOST
func (s *Session) Read(p []byte) (n int, err error) {
	return s.read(p)
}

// Write writes data to device or interface synchronously.
//
// This operation synchronously transfers data. The data to be written is in the buffer represented by buf. This operation returns only when the transfer terminates. Only one synchronous write operation can occur at any one time.
//
// Possible Errors:
//     ERROR_INV_OBJECT
//     ERROR_NSUP_OPER
//     ERROR_RSRC_LOCKED
//     ERROR_TMO
//     ERROR_RAW_WR_PROT_VIOL
//     ERROR_RAW_RD_PROT_VIOL
//     ERROR_INP_PROT_VIOL
//     ERROR_BERR
//     ERROR_INV_SETUP
//     ERROR_NCIC
//     ERROR_NLISTENERS
//     ERROR_IO
//     ERROR_CONN_LOST
func (s *Session) Write(p []byte) (n int, err error) {
	return s.write(p)
}

// AssertTrigger asserts software or hardware trigger.
//
// This operation sources a software or hardware trigger dependent on the interface type.
//
// Possible Errors:
//     ERROR_INV_OBJECT
//     ERROR_NSUP_OPER
//     ERROR_RSRC_LOCKED
//     ERROR_INV_PROT
//     ERROR_TMO
//     ERROR_RAW_WR_PROT_VIOL
//     ERROR_RAW_RD_PROT_VIOL
//     ERROR_INP_PROT_VIOL
//     ERROR_BERR
//     ERROR_LINE_IN_USE
//     ERROR_NCIC
//     ERROR_NLISTENERS
//     ERROR_INV_SETUP
//     ERROR_CONN_LOST
func (s *Session) AssertTrigger(protocol TriggerProtocol) error {
	return s.assertTrigger(protocol)
}

// ReadSTB reads a status byte of the service request.
//
// Possible Errors:
//     ERROR_INV_OBJECT
//     ERROR_NSUP_OPER
//     ERROR_RSRC_LOCKED
//     ERROR_SRQ_NOCCURRED
//     ERROR_TMO
//     ERROR_RAW_WR_PROT_VIOL
//     ERROR_RAW_RD_PROT_VIOL
//     ERROR_BERR
//     ERROR_NCIC
//     ERROR_NLISTENERS
//     ERROR_INV_SETUP
//     ERROR_CONN_LOST
func (s *Session) ReadSTB() (statusByte uint16, err error) {
	return s.readSTB()
}

// Clear clears a device.
//
// This operation clears the device input and output buffers.
//
// Possible Errors:
//     ERROR_INV_OBJECT
//     ERROR_NSUP_OPER
//     ERROR_RSRC_LOCKED
//     ERROR_TMO
//     ERROR_RAW_WR_PROT_VIOL
//     ERROR_RAW_RD_PROT_VIOL
//     ERROR_BERR
//     ERROR_NCIC
//     ERROR_NLISTENERS
//     ERROR_INV_SETUP
//     ERROR_CONN_LOST
func (s *Session) Clear() error {
	return s.clear()
}

func (s *Session) WaitOnEvent(inEventType EventType, timeout int) (event *Event, err error) {
	if timeout < -1 {
		panic(fmt.Sprintf("invalid timeout %d", timeout))
	}
	return s.waitOnEvent(inEventType, uint32(int32(timeout)))
}

func (e *Event) Type() EventType {
	return e.eventType
}

func (e *Event) Close() error {
	return e.close()
}