KsCreateComm

The availability of this function depends on what the device supports.

Opens a COM port that is connected to an EtherCAT slave. The EtherCAT network must be established for it to succeed.

Syntax

HANDLE KsCreateComm(
     LPCTSTR lpFileName,
     DWORD dwDesiredAccess,
     DWORD dwShareMode,
     LPSECURITY_ATTRIBUTES lpSecurityAttributes,
     DWORD dwCreationDisposition,
     DWORD dwFlagsAndAttributes,
     HANDLE hTemplateFile
);

Parameters

lpFileName: a pointer to a null-terminated string that specifies the location of the port to open. The KsCreateComm function cannot be used to create or open files or local COM ports. It can open only the COM ports connected to an EtherCAT device. The string format is COM 1.0 is the index of the EtherCAT I/O containing the COM port and 0 is the index of the port on that device.

dwDesiredAccess: the type of access to the object. An application can obtain read access, write access, read-write access, or device query access. This parameter can be any combination of the following values.

Value	Description
0 (zero)	Specifies device query access to the object. An application can query device attributes without accessing the device.
WIN32_GENERIC_EXECUTE	The right to execute the file.
GENERIC_READ	Specifies read access to the object. Data can be read from the file and the file pointer can be moved. Combine with GENERIC_WRITE for read-write access.
GENERIC_WRITE	Specifies write access to the object. Data can be written to the file and the file pointer can be moved. Combine with GENERIC_READ for read-write access.

dwShareMode: set of bit flags that specifies how the object can be shared. If dwShareMode is 0, the object cannot be shared. Subsequent open operations on the object will fail, until the handle is closed.

To share the object, use a combination of one or more of the following values:

Value	Description
FILE_SHARE_DELETE	Subsequent open operations on the object will succeed only if delete access is requested.
FILE_SHARE_READ	Subsequent open operations on the object will succeed only if read access is requested.
FILE_SHARE_WRITE	Subsequent open operations on the object will succeed only if write access is requested.

lpSecurityAttributes: a pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

The lpSecurityDescriptor member of the structure specifies a security descriptor for the object. If lpSecurityAttributes is NULL, the object gets a default security descriptor. The target file system must support security on files and directories for this parameter to have an effect on files.

dwCreationDisposition: ignored. Always opens an existing COM port.

dwFlagsAndAttributes: the port attributes.

Value	Description
Bit 0	Continuous access
Bit 1	Rate optimization
Bit 2	Half duplex
Bit 3	Point to Point

hTemplateFile: ignored.

Return value

An open handle to the specified COM port if the function succeeds, an INVALID_HANDLE_VALUE if the function fails. To get extended error information, call GetLastError.

Remarks

Use KsCloseComm to close an object handle returned by KsCreateComm.
As noted above, specifying zero for dwDesiredAccess allows an application to query device attributes without actually accessing the device. This type of querying is useful, for example, if an application wants to determine the size of a floppy disk drive and the formats it supports without having a floppy in the drive.
Some SDO commands are device specific (6001 or 6021) so they fail on the other type. KINGSTAR sends all settings for both types (600X and 602X) and ignores the commands that fail. This is expected and not an issue.
The SDO commands are sent twice: once when initializing and once when configuring.

Example

N/A

Requirements

	RT	Win32
Minimum supported version	4.0	4.0
Header	kscom.h	kscom.h
Library	KsApi_Rtss.lib	ksapi.h