CommInterface.au3: Difference between revisions

From AutoIt Wiki
Jump to navigation Jump to search
No edit summary
(fix error in _CommAPI_ReceiveBinary)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<syntaxhighlight lang="autoit">
[[Category:CommAPI]][[Category:Script]]<syntaxhighlight lang="autoit">
; #INDEX# =======================================================================================================================
; #INDEX# =======================================================================================================================
; Name ..........: CommInterface.au3
; Name ..........: CommInterface.au3
; Title .........: Communications Functions of Windows API
; Title .........: Communications Functions of Windows API
; Description ...: Communications Functions of Windows API calls that have been translated to AutoIt functions.
; Description ...: Communications Functions of Windows API calls that have been translated to AutoIt functions.
; Version Date ..: 2013-10-24
; Version Date ..: 2014-04-08
; AutoIt Version : 3.3.8.1
; AutoIt Version : 3.3.8.1
; Link ..........: http://msdn.microsoft.com/en-us/library/aa363194(v=vs.85).aspx
; Link ..........: http://msdn.microsoft.com/en-us/library/aa363194(v=vs.85).aspx
Line 10: Line 10:
; Author(s) .....:
; Author(s) .....:
; Dll(s) ........: kernel32.dll
; Dll(s) ........: kernel32.dll
; Error handling : Everytime @extended is set, it is filled with @ScriptLineNumber of the error in CommAPI.au3.
; Error handling : Everytime @extended is set, it is filled with @ScriptLineNumber of the error.
;                  Everytime @extended is set, you can call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage.
; ===============================================================================================================================
; ===============================================================================================================================


Line 28: Line 27:
; Return values .: Success - True
; Return values .: Success - True
;                  Failure - False
;                  Failure - False
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                          -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Author ........:
; Modified ......:
; Modified ......:
Line 36: Line 41:
; ===============================================================================================================================
; ===============================================================================================================================
Func _CommAPI_ClosePort(Const $hFile)
Func _CommAPI_ClosePort(Const $hFile)
Local $fResult = _WinAPI_CloseHandle($hFile)
Local $fSuccess = _WinAPI_CloseHandle($hFile)
If @error Then Return SetError(@error, 0, False)
If @error Then Return SetError(@error, 0, False)
Return $fResult
If Not $fSuccess Then Return SetError(-1, @ScriptLineNumber, False)
Return $fSuccess
EndFunc  ;==>_CommAPI_ClosePort
EndFunc  ;==>_CommAPI_ClosePort


Line 45: Line 51:
; Description ...: Opens a COM Port.
; Description ...: Opens a COM Port.
; Syntax ........: _CommAPI_OpenCOMPort(Const $iPort[, $iBaudRate = Default[, $iParity = Default[, $iByteSize = Default[,
; Syntax ........: _CommAPI_OpenCOMPort(Const $iPort[, $iBaudRate = Default[, $iParity = Default[, $iByteSize = Default[,
;                  $iStopBits = Default[, $iReadTotalTimeout = 100]]]]])
;                  $iStopBits = Default]]]])
; Parameters ....: $iPort              - [in] A port number.
; Parameters ....: $iPort              - [in] A port number.
;                  $iBaudRate          - [in] The baud rate at which the communications device operates.
;                  $iBaudRate          - [in] The baud rate at which the communications device operates.
Line 51: Line 57:
;                  $iByteSize          - [in] Specifies the number of data bits in a character.
;                  $iByteSize          - [in] Specifies the number of data bits in a character.
;                  $iStopBits          - [in] Specifies the number of stop bits that define the end of a character: 1, 1.5, or 2.
;                  $iStopBits          - [in] Specifies the number of stop bits that define the end of a character: 1, 1.5, or 2.
;                  $iReadTotalTimeout  - [in] An integer value for total read timeout in milliseconds.
; Return values .: Success - Open handle to a specified communications device
; Return values .: Success - The open handle to a specified communications device.
;                  Failure - 0
;                  Failure - 0
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                            11 struct not a correct struct returned by DllStructCreate
;                            12 element value out of range
;                            13 index would be outside of the struct
;                            14 element data type is unknown
;                            15 index <= 0
;                          -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Author ........:
; Modified ......:
; Modified ......:
; Remarks .......:
; Remarks .......:
; Related .......: _CommAPI_OpenPort, _CommAPI_ClosePort, _CommAPI_CreateModeString
; Related .......: _CommAPI_OpenPort, _CommAPI_ClosePort, _CommAPI_CreateModeString
; Link ..........: http://msdn.microsoft.com/en-us/library/aa363214(v=vs.85).aspx
; Link ..........:
; Example .......: No
; Example .......: No
; ===============================================================================================================================
; ===============================================================================================================================
Func _CommAPI_OpenCOMPort(Const $iPort, Const $iBaudRate = Default, Const $iParity = Default, Const $iByteSize = Default, Const $iStopBits = Default, Const $iReadTotalTimeout = 100)
Func _CommAPI_OpenCOMPort(Const $iPort, Const $iBaudRate = Default, Const $iParity = Default, Const $iByteSize = Default, Const $iStopBits = Default)
Local $sMode = _CommAPI_CreateModeString($iPort, $iBaudRate, $iParity, $iByteSize, $iStopBits)
Local $sMode = _CommAPI_CreateModeString($iPort, $iBaudRate, $iParity, $iByteSize, $iStopBits)
Local $hFile = _CommAPI_OpenPort($sMode, $iReadTotalTimeout)
Local $hFile = _CommAPI_OpenPort($sMode)
If @error Then Return SetError(@error, @extended, 0)
If @error Then Return SetError(@error, @extended, 0)
Return $hFile
Return $hFile
Line 71: Line 87:
; Name ..........: _CommAPI_OpenPort
; Name ..........: _CommAPI_OpenPort
; Description ...: Opens a specified communications device.
; Description ...: Opens a specified communications device.
; Syntax ........: _CommAPI_OpenPort(Const $sMode[, $iReadTotalTimeout = 100])
; Syntax ........: _CommAPI_OpenPort(Const $sMode)
; Parameters ....: $sMode              - [in] A device-definition string.
; Parameters ....: $sMode              - [in] A device-definition string.
;                  $iReadTotalTimeout  - [in] An integer value for total read timeout in milliseconds.
; Return values .: Success - Open handle to a specified communications device
; Return values .: Success - The open handle to a specified communications device.
;                  Failure - 0
;                  Failure - 0
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                            11 struct not a correct struct returned by DllStructCreate
;                            12 element value out of range
;                            13 index would be outside of the struct
;                            14 element data type is unknown
;                            15 index <= 0
;                          -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Author ........:
; Modified ......:
; Modified ......:
; Remarks .......:
; Remarks .......:
; Related .......: _CommAPI_OpenCOMPort, _CommAPI_ClosePort, _CommAPI_SetCommState
; Related .......: _CommAPI_OpenCOMPort, _CommAPI_ClosePort, _CommAPI_SetCommState
; Link ..........: http://msdn.microsoft.com/en-us/library/aa363214(v=vs.85).aspx
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365430(v=vs.85).aspx
; Example .......: No
; Example .......: No
; ===============================================================================================================================
; ===============================================================================================================================
Func _CommAPI_OpenPort(Const $sMode, Const $iReadTotalTimeout = 100)
Func _CommAPI_OpenPort(Const $sMode)
Local $sFileName = "\\.\" & StringLeft($sMode, StringInStr($sMode, ":") - 1)
Local $sFileName = "\\.\" & StringLeft($sMode, StringInStr($sMode, ":") - 1)
Local $hFile = _WinAPI_CreateFile($sFileName, 2, 6)
Local $hFile = _WinAPI_CreateFile($sFileName, 3, 6)
If @error Then Return SetError(@error, @ScriptLineNumber, 0)
If @error Then Return SetError(@error, @ScriptLineNumber, 0)
If $hFile <= 0 Then Return SetError(-1, @ScriptLineNumber, 0)
If $hFile <= 0 Then Return SetError(-1, @ScriptLineNumber, 0)
Line 92: Line 118:
Local $tCommTimeouts = DllStructCreate($tagCOMMTIMEOUTS)
Local $tCommTimeouts = DllStructCreate($tagCOMMTIMEOUTS)


_CommAPI_BuildCommDCBAndTimeouts($sMode, $tDCB, $tCommTimeouts)
_CommAPI_BuildCommDCB($sMode, $tDCB)
If @error Then Return SetError(@error, @extended, 0)
 
_CommAPI_SetCommTimeoutsElement($tCommTimeouts, "ReadTotalTimeoutMultiplier", 1)
If @error Then Return SetError(@error, @extended, 0)
If @error Then Return SetError(@error, @extended, 0)


_CommAPI_SetCommTimeoutsElement($tCommTimeouts, "ReadTotalTimeoutConstant", $iReadTotalTimeout)
_CommAPI_SetCommTimeoutsElement($tCommTimeouts, "WriteTotalTimeoutMultiplier", 1)
If @error Then Return SetError(@error, @extended, 0)
If @error Then Return SetError(@error, @extended, 0)


Line 105: Line 134:


; #FUNCTION# ====================================================================================================================
; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_ReceiveData
; Name ..........: _CommAPI_ReceiveBinary
; Description ...: Receives data (RxD/RX/RD) to a specified communications device.
; Syntax ........: _CommAPI_ReceiveBinary(Const $hFile[, $iTimeout = 1[, $iMaxLength = 0[, $vSeparator = ""]]])
; Parameters ....: $hFile              - [in] A handle to the communications device.
;                  $iTimeout            - [in] An integer value for total read timeout in milliseconds.
;                                              Is activated only by positive values.
;                  $iMaxLength          - [in] An integer value for maximum length of result.
;                                              Is activated only by positive values.
;                  $vSeparator          - [in] A value which is used as a separator.
;                                              Is activated only by non-empty values.
; Return values .: Success - Received binary data
;                  Failure - Received binary data
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                          -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
;                          -2 timeout
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_ReceiveString, _CommAPI_TransmitData
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365467(v=vs.85).aspx
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_ReceiveBinary(Const $hFile, Const $iTimeout = 1, Const $iMaxLength = 0, Const $vSeparator = "")
Local $bSeparator = Binary($vSeparator)
Local $iSepLength = BinaryLen($bSeparator)
Local $fSuccess = False
Local $tBuffer = DllStructCreate("BYTE")
Local $pBuffer = DllStructGetPtr($tBuffer)
Local $iRead = 0
Local $bResult = Binary("")
Local $iResLength = 0
Local $hTimer = TimerInit()
While True
$fSuccess = _WinAPI_ReadFile($hFile, $pBuffer, 1, $iRead)
If @error Then Return SetError(@error, @ScriptLineNumber, $bResult)
If Not $fSuccess Then Return SetError(-1, @ScriptLineNumber, $bResult)
If $iRead Then
$bResult &= BinaryMid(Binary(DllStructGetData($tBuffer, 1)), 1, 1)
$iResLength = BinaryLen($bResult)
If $iMaxLength And $iResLength = $iMaxLength Then Return $bResult
If $iSepLength And $bSeparator = BinaryMid($bResult, 1 + $iResLength - $iSepLength) Then Return BinaryMid($bResult, 1, $iResLength - $iSepLength)
Else
If $bResult And Not $iSepLength Then Return $bResult
If $iTimeout And $iTimeout < TimerDiff($hTimer) Then Return SetError(-2, @ScriptLineNumber, $bResult)
EndIf
WEnd
EndFunc  ;==>_CommAPI_ReceiveBinary
 
; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_ReceiveString
; Description ...: Receives data (RxD/RX/RD) to a specified communications device.
; Description ...: Receives data (RxD/RX/RD) to a specified communications device.
; Syntax ........: _CommAPI_ReceiveData(Const $hFile[, $iMinBufferSize = 1[, $iMaxWaitTime = 100]])
; Syntax ........: _CommAPI_ReceiveString(Const $hFile[, $iTimeout = 1[, $iMaxLength = 0[, $sSeparator = ""]]])
; Parameters ....: $hFile              - [in] A handle to the communications device.
; Parameters ....: $hFile              - [in] A handle to the communications device.
;                  $iTimeout            - [in] An integer value for total read timeout in milliseconds.
;                                              Is activated only by positive values.
;                  $iMaxLength          - [in] An integer value for maximum length of result.
;                                              Is activated only by positive values.
;                  $sSeparator          - [in] A value which is used as a separator.
;                                              Is activated only by non-empty values.
;                  $iFlag              - [in] Flag for function BinaryToString().
; Return values .: Success - Received string
; Return values .: Success - Received string
;                  Failure - Empty string
;                  Failure - Received string
;                            Received binary data in case of @error = -3
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                          -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
;                          -2 timeout
;                          -3 error in BinaryToString
; Author ........:
; Author ........:
; Modified ......:
; Modified ......:
; Remarks .......: If the result contains Chr(0), you should convert the result with function Binary().
; Remarks .......:
; Related .......: _CommAPI_TransmitData
; Related .......: _CommAPI_ReceiveBinary, _CommAPI_TransmitData
; Link ..........:
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365467(v=vs.85).aspx
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_ReceiveString(Const $hFile, Const $iTimeout = 1, Const $iMaxLength = 0, Const $sSeparator = "", Const $iFlag = 1)
Local $bResult = _CommAPI_ReceiveBinary($hFile, $iTimeout, $iMaxLength, StringToBinary($sSeparator, $iFlag))
Local $iError = @error
Local $iExtended = @extended
Local $sResult = ""
If $bResult Then
$sResult = BinaryToString($bResult, $iFlag)
If @error Then SetError(-3, @ScriptLineNumber, $bResult)
EndIf
Return SetError($iError, $iExtended, $sResult)
EndFunc  ;==>_CommAPI_ReceiveString
 
; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_TransmitBinary
; Description ...: Transmits data (TxD/TX/TD) to a specified communications device.
; Syntax ........: _CommAPI_TransmitData(Const $hFile, Const $sData)
; Parameters ....: $hFile              - [in] A handle to the communications device.
;                  $vData              - [in] A binary value to transmit.
; Return values .: Success - Number of written bytes
;                  Failure - Number of written bytes
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                          -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_TransmitString, _CommAPI_ReceiveBinary
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365747(v=vs.85).aspx
; Example .......: No
; Example .......: No
; ===============================================================================================================================
; ===============================================================================================================================
Func _CommAPI_ReceiveData(Const $hFile)
Func _CommAPI_TransmitBinary(Const $hFile, Const $vData)
Local $tBuffer = DllStructCreate("char")
Local $bData = Binary($vData)
Local $iLength = BinaryLen($vData)
Local $iWritten = 0
Local $iWritten = 0
Local $sResult = ""
Local $tBuffer = DllStructCreate("BYTE[" & $iLength & "]")
Do
DllStructSetData($tBuffer, 1, $bData)
_WinAPI_ReadFile($hFile, DllStructGetPtr($tBuffer), 1, $iWritten)
Local $fSuccess = _WinAPI_WriteFile($hFile, DllStructGetPtr($tBuffer), $iLength, $iWritten)
If @error Then Return SetError(@error, 0, $sResult)
If @error Then Return SetError(@error, @ScriptLineNumber, 0)
If $iWritten Then $sResult &= DllStructGetData($tBuffer, 1)
If Not $fSuccess Then Return SetError(-1, @ScriptLineNumber, $iWritten)
Until Not $iWritten
Return $iWritten
Return $sResult
EndFunc  ;==>_CommAPI_TransmitBinary
EndFunc  ;==>_CommAPI_ReceiveData


; #FUNCTION# ====================================================================================================================
; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_TransmitData
; Name ..........: _CommAPI_TransmitString
; Description ...: Transmits data (TxD/TX/TD) to a specified communications device.
; Description ...: Transmits data (TxD/TX/TD) to a specified communications device.
; Syntax ........: _CommAPI_TransmitData(Const $hFile, Const $sData)
; Syntax ........: _CommAPI_TransmitData(Const $hFile, Const $sData)
; Parameters ....: $hFile              - [in] A handle to the communications device.
; Parameters ....: $hFile              - [in] A handle to the communications device.
;                  $sData              - [in] A string value to transmit.
;                  $sData              - [in] A string value to transmit.
; Return values .: Success - The number of bytes written.
;                  $iFlag              - [in] Flag for function StringToBinary().
;                  Failure - 0
; Return values .: Success - Number of written bytes
;                  Failure - Number of written bytes
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                          -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Author ........:
; Modified ......:
; Modified ......:
; Remarks .......:
; Remarks .......:
; Related .......: _CommAPI_ReceiveData
; Related .......: _CommAPI_TransmitBinary, _CommAPI_ReceiveString
; Link ..........:
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365747(v=vs.85).aspx
; Example .......: No
; Example .......: No
; ===============================================================================================================================
; ===============================================================================================================================
Func _CommAPI_TransmitData(Const $hFile, Const $sData)
Func _CommAPI_TransmitString(Const $hFile, Const $sData, Const $iFlag = 1)
Local $iWritten = 0
Local $iWritten = _CommAPI_TransmitBinary($hFile, StringToBinary($sData, $iFlag))
Local $tBuffer = DllStructCreate("byte[" & StringLen($sData) & "]")
If @error Then Return SetError(@error, @extended, $iWritten)
DllStructSetData($tBuffer, 1, $sData)
If @error Then Return SetError(@error)
_WinAPI_WriteFile($hFile, DllStructGetPtr($tBuffer), StringLen($sData), $iWritten)
If @error Then Return SetError(@error)
Return $iWritten
Return $iWritten
EndFunc   ;==>_CommAPI_TransmitData
EndFunc
</syntaxhighlight>
</syntaxhighlight>

Latest revision as of 13:30, 8 April 2014

; #INDEX# =======================================================================================================================
; Name ..........: CommInterface.au3
; Title .........: Communications Functions of Windows API
; Description ...: Communications Functions of Windows API calls that have been translated to AutoIt functions.
; Version Date ..: 2014-04-08
; AutoIt Version : 3.3.8.1
; Link ..........: http://msdn.microsoft.com/en-us/library/aa363194(v=vs.85).aspx
; Tag(s) ........: RS-232, serial port, COM port
; Author(s) .....:
; Dll(s) ........: kernel32.dll
; Error handling : Everytime @extended is set, it is filled with @ScriptLineNumber of the error.
; ===============================================================================================================================

#include-once
#include "CommAPIHelper.au3"
#include "CommUtilities.au3"
#include <WinAPI.au3>
#NoAutoIt3Execute
#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w 1 -w 2 -w 3 -w- 4 -w 5 -w 6 -w- 7

; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_ClosePort
; Description ...: CLoses a specified communications device.
; Syntax ........: _CommAPI_ClosePort(Const $hFile)
; Parameters ....: $hFile               - [in] A handle to the communications device.
; Return values .: Success - True
;                  Failure - False
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                           -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_OpenPort
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_ClosePort(Const $hFile)
	Local $fSuccess = _WinAPI_CloseHandle($hFile)
	If @error Then Return SetError(@error, 0, False)
	If Not $fSuccess Then Return SetError(-1, @ScriptLineNumber, False)
	Return $fSuccess
EndFunc   ;==>_CommAPI_ClosePort

; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_OpenCOMPort
; Description ...: Opens a COM Port.
; Syntax ........: _CommAPI_OpenCOMPort(Const $iPort[, $iBaudRate = Default[, $iParity = Default[, $iByteSize = Default[,
;                  $iStopBits = Default]]]])
; Parameters ....: $iPort               - [in] A port number.
;                  $iBaudRate           - [in] The baud rate at which the communications device operates.
;                  $iParity             - [in] The parity scheme to be used.
;                  $iByteSize           - [in] Specifies the number of data bits in a character.
;                  $iStopBits           - [in] Specifies the number of stop bits that define the end of a character: 1, 1.5, or 2.
; Return values .: Success - Open handle to a specified communications device
;                  Failure - 0
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                            11 struct not a correct struct returned by DllStructCreate
;                            12 element value out of range
;                            13 index would be outside of the struct
;                            14 element data type is unknown
;                            15 index <= 0
;                           -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_OpenPort, _CommAPI_ClosePort, _CommAPI_CreateModeString
; Link ..........:
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_OpenCOMPort(Const $iPort, Const $iBaudRate = Default, Const $iParity = Default, Const $iByteSize = Default, Const $iStopBits = Default)
	Local $sMode = _CommAPI_CreateModeString($iPort, $iBaudRate, $iParity, $iByteSize, $iStopBits)
	Local $hFile = _CommAPI_OpenPort($sMode)
	If @error Then Return SetError(@error, @extended, 0)
	Return $hFile
EndFunc   ;==>_CommAPI_OpenCOMPort

; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_OpenPort
; Description ...: Opens a specified communications device.
; Syntax ........: _CommAPI_OpenPort(Const $sMode)
; Parameters ....: $sMode               - [in] A device-definition string.
; Return values .: Success - Open handle to a specified communications device
;                  Failure - 0
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                            11 struct not a correct struct returned by DllStructCreate
;                            12 element value out of range
;                            13 index would be outside of the struct
;                            14 element data type is unknown
;                            15 index <= 0
;                           -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_OpenCOMPort, _CommAPI_ClosePort, _CommAPI_SetCommState
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365430(v=vs.85).aspx
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_OpenPort(Const $sMode)
	Local $sFileName = "\\.\" & StringLeft($sMode, StringInStr($sMode, ":") - 1)
	Local $hFile = _WinAPI_CreateFile($sFileName, 3, 6)
	If @error Then Return SetError(@error, @ScriptLineNumber, 0)
	If $hFile <= 0 Then Return SetError(-1, @ScriptLineNumber, 0)

	Local $tDCB = DllStructCreate($tagDCB)
	Local $tCommTimeouts = DllStructCreate($tagCOMMTIMEOUTS)

	_CommAPI_BuildCommDCB($sMode, $tDCB)
	If @error Then Return SetError(@error, @extended, 0)

	_CommAPI_SetCommTimeoutsElement($tCommTimeouts, "ReadTotalTimeoutMultiplier", 1)
	If @error Then Return SetError(@error, @extended, 0)

	_CommAPI_SetCommTimeoutsElement($tCommTimeouts, "WriteTotalTimeoutMultiplier", 1)
	If @error Then Return SetError(@error, @extended, 0)

	If Not _CommAPI_SetCommState($hFile, $tDCB) Then Return SetError(@error, @extended, 0)
	If Not _CommAPI_SetCommTimeouts($hFile, $tCommTimeouts) Then Return SetError(@error, @extended, 0)

	Return $hFile
EndFunc   ;==>_CommAPI_OpenPort

; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_ReceiveBinary
; Description ...: Receives data (RxD/RX/RD) to a specified communications device.
; Syntax ........: _CommAPI_ReceiveBinary(Const $hFile[, $iTimeout = 1[, $iMaxLength = 0[, $vSeparator = ""]]])
; Parameters ....: $hFile               - [in] A handle to the communications device.
;                  $iTimeout            - [in] An integer value for total read timeout in milliseconds.
;                                              Is activated only by positive values.
;                  $iMaxLength          - [in] An integer value for maximum length of result.
;                                              Is activated only by positive values.
;                  $vSeparator          - [in] A value which is used as a separator.
;                                              Is activated only by non-empty values.
; Return values .: Success - Received binary data
;                  Failure - Received binary data
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                           -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
;                           -2 timeout
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_ReceiveString, _CommAPI_TransmitData
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365467(v=vs.85).aspx
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_ReceiveBinary(Const $hFile, Const $iTimeout = 1, Const $iMaxLength = 0, Const $vSeparator = "")
	Local $bSeparator = Binary($vSeparator)
	Local $iSepLength = BinaryLen($bSeparator)
	Local $fSuccess = False
	Local $tBuffer = DllStructCreate("BYTE")
	Local $pBuffer = DllStructGetPtr($tBuffer)
	Local $iRead = 0
	Local $bResult = Binary("")
	Local $iResLength = 0
	Local $hTimer = TimerInit()
	While True
		$fSuccess = _WinAPI_ReadFile($hFile, $pBuffer, 1, $iRead)
		If @error Then Return SetError(@error, @ScriptLineNumber, $bResult)
		If Not $fSuccess Then Return SetError(-1, @ScriptLineNumber, $bResult)
		If $iRead Then
			$bResult &= BinaryMid(Binary(DllStructGetData($tBuffer, 1)), 1, 1)
			$iResLength = BinaryLen($bResult)
			If $iMaxLength And $iResLength = $iMaxLength Then Return $bResult
			If $iSepLength And $bSeparator = BinaryMid($bResult, 1 + $iResLength - $iSepLength) Then Return BinaryMid($bResult, 1, $iResLength - $iSepLength)
		Else
			If $bResult And Not $iSepLength Then Return $bResult
			If $iTimeout And $iTimeout < TimerDiff($hTimer) Then Return SetError(-2, @ScriptLineNumber, $bResult)
		EndIf
	WEnd
EndFunc   ;==>_CommAPI_ReceiveBinary

; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_ReceiveString
; Description ...: Receives data (RxD/RX/RD) to a specified communications device.
; Syntax ........: _CommAPI_ReceiveString(Const $hFile[, $iTimeout = 1[, $iMaxLength = 0[, $sSeparator = ""]]])
; Parameters ....: $hFile               - [in] A handle to the communications device.
;                  $iTimeout            - [in] An integer value for total read timeout in milliseconds.
;                                              Is activated only by positive values.
;                  $iMaxLength          - [in] An integer value for maximum length of result.
;                                              Is activated only by positive values.
;                  $sSeparator          - [in] A value which is used as a separator.
;                                              Is activated only by non-empty values.
;                  $iFlag               - [in] Flag for function BinaryToString().
; Return values .: Success - Received string
;                  Failure - Received string
;                            Received binary data in case of @error = -3
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                           -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
;                           -2 timeout
;                           -3 error in BinaryToString
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_ReceiveBinary, _CommAPI_TransmitData
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365467(v=vs.85).aspx
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_ReceiveString(Const $hFile, Const $iTimeout = 1, Const $iMaxLength = 0, Const $sSeparator = "", Const $iFlag = 1)
	Local $bResult = _CommAPI_ReceiveBinary($hFile, $iTimeout, $iMaxLength, StringToBinary($sSeparator, $iFlag))
	Local $iError = @error
	Local $iExtended = @extended
	Local $sResult = ""
	If $bResult Then
		$sResult = BinaryToString($bResult, $iFlag)
		If @error Then SetError(-3, @ScriptLineNumber, $bResult)
	EndIf
	Return SetError($iError, $iExtended, $sResult)
EndFunc   ;==>_CommAPI_ReceiveString

; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_TransmitBinary
; Description ...: Transmits data (TxD/TX/TD) to a specified communications device.
; Syntax ........: _CommAPI_TransmitData(Const $hFile, Const $sData)
; Parameters ....: $hFile               - [in] A handle to the communications device.
;                  $vData               - [in] A binary value to transmit.
; Return values .: Success - Number of written bytes
;                  Failure - Number of written bytes
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                           -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_TransmitString, _CommAPI_ReceiveBinary
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365747(v=vs.85).aspx
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_TransmitBinary(Const $hFile, Const $vData)
	Local $bData = Binary($vData)
	Local $iLength = BinaryLen($vData)
	Local $iWritten = 0
	Local $tBuffer = DllStructCreate("BYTE[" & $iLength & "]")
	DllStructSetData($tBuffer, 1, $bData)
	Local $fSuccess = _WinAPI_WriteFile($hFile, DllStructGetPtr($tBuffer), $iLength, $iWritten)
	If @error Then Return SetError(@error, @ScriptLineNumber, 0)
	If Not $fSuccess Then Return SetError(-1, @ScriptLineNumber, $iWritten)
	Return $iWritten
EndFunc   ;==>_CommAPI_TransmitBinary

; #FUNCTION# ====================================================================================================================
; Name ..........: _CommAPI_TransmitString
; Description ...: Transmits data (TxD/TX/TD) to a specified communications device.
; Syntax ........: _CommAPI_TransmitData(Const $hFile, Const $sData)
; Parameters ....: $hFile               - [in] A handle to the communications device.
;                  $sData               - [in] A string value to transmit.
;                  $iFlag               - [in] Flag for function StringToBinary().
; Return values .: Success - Number of written bytes
;                  Failure - Number of written bytes
;                  @error  - 1 unable to use the DLL file
;                            2 unknown "return type"
;                            3 "function" not found in the DLL file
;                            4 bad number of parameters
;                            5 bad parameter
;                           -1 function fails (To get extended error information, call _WinAPI_GetLastError or _WinAPI_GetLastErrorMessage)
; Author ........:
; Modified ......:
; Remarks .......:
; Related .......: _CommAPI_TransmitBinary, _CommAPI_ReceiveString
; Link ..........: http://msdn.microsoft.com/en-us/library/aa365747(v=vs.85).aspx
; Example .......: No
; ===============================================================================================================================
Func _CommAPI_TransmitString(Const $hFile, Const $sData, Const $iFlag = 1)
	Local $iWritten = _CommAPI_TransmitBinary($hFile, StringToBinary($sData, $iFlag))
	If @error Then Return SetError(@error, @extended, $iWritten)
	Return $iWritten
EndFunc
Retrieved from "https://www.autoitscript.com/w/index.php?title=CommInterface.au3&oldid=12375"