Port related functions

Functions

PCHAR TcPortGetName (TC_PORT port)
 It returns the name of a given port.
TC_STATUS TcPortQueryBoard (TC_PORT port, PTC_BOARD pBoard)
 It returns the board handle containing the given port.
PCHAR TcPortGetDescription (TC_PORT port)
 It returns the description of a given port.
TC_STATUS TcPortSetDescription (TC_PORT port, PCHAR pPortName)
 It sets the description of a given physical port.
TC_PORT_TYPE TcPortGetType (TC_PORT port)
 It returns the type of a given port.
TC_STATUS TcPortQueryMacAddress (TC_PORT port, BYTE pMac[6])
 It queries a port for the MAC address.
TC_STATUS TcPortQueryAggregatedPortList (TC_PORT aggregatingPort, PTC_PORT *ppPorts, PULONG pLength)
 It queries an aggregating port for the list of physical ports that it aggregates.
BOOLEAN TcPortIsEqual (TC_PORT portA, TC_PORT portB)
 It compares two port handles to check if they correspond to the same port.
TC_STATUS TcPortQueryLinkStatus (TC_PORT port, PTC_LINK_INFO pLinkInfo)
 Queries a port for the link status.
TC_STATUS TcPortQueryStatistics (TC_PORT port, PTC_STATISTICS pStatistics)
 It queries the statistics of a physical port.
TC_STATUS TcPortSetFeature (TC_PORT port, ULONG feature, ULONG value)
 It sets a specific feature on the port.
TC_STATUS TcPortQueryFeature (TC_PORT port, ULONG feature, PULONG pValue)
 It queries a specific feature on the port.
TC_STATUS TcPortSetAutonegotiationParameters (TC_PORT port, TC_AUTONEG_PARAMETERS autonegParameters)
 It sets the autonegotiation parameters of a physical port i.e. it enables/disables autonegotiation and controls which link speeds should be advertised during autonegotiation.
TC_STATUS TcPortQueryAutonegotiationParameters (TC_PORT port, PTC_AUTONEG_PARAMETERS pAutonegParameters)
 It queries the autonegotiation parameters of a port i.e. if autonegotiation is enabled, which link speed be advertised during autonegotiation and which link speeds are supported by the port.

Function Documentation

PCHAR TcPortGetName ( TC_PORT  port  ) 

It returns the name of a given port.

Parameters:
port The handle of a port to query for the name
Returns:
Pointer to a string containing the port name.
Note:
  • the returned name string must not be freed.
  • the returned name is unique on a machine.
  • the returned string should not be modified.
  • the name can be used in a subsequent call to TcInstanceOpenByName.
  • the returned string until the given port handle is valid. If the port handle comes from a list returned by TcQueryPortList, the name is valid until the list is destroyed. If the handle comes (directly or indirectly) from an instance (TC_INSTANCE), then the name is valid until the instance is closed.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortQueryBoard ( TC_PORT  port,
PTC_BOARD  pBoard 
)

It returns the board handle containing the given port.

Parameters:
port The handle of a port to query for the board
pBoard Pointer to a board handle. On success it will contain the handle to the board.
Note:
  • the returned handle must not be freed.
  • the returned handle until the given port handle is valid. If the port handle comes from a list returned by TcQueryPortList, the board is valid until the list is destroyed. If the port handle comes (directly or indirectly) from an instance (TC_INSTANCE), then the board handle is valid until the instance is closed.
Returns:
TC_SUCCESS in case of a physical or BAP port, TC_ERROR_INVALID_REQUEST in case of a TcAP port.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

PCHAR TcPortGetDescription ( TC_PORT  port  ) 

It returns the description of a given port.

Parameters:
port The handle of a port to get the description from.
Returns:
Pointer to a string containing the port description.
Note:
  • the description string must not be freed.
  • the description is not unique on a machine i.e. multiple ports with different names can have the same description.
  • the returned string should not be modified.
  • the returned string until the given port handle is valid. If the port handle comes from a list returned by TcQueryPortList, the string is valid until the list is destroyed. If the handle comes (directly or indirectly) from an instance (TC_INSTANCE), then the string is valid until the instance is closed.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortSetDescription ( TC_PORT  port,
PCHAR  pPortName 
)

It sets the description of a given physical port.

Parameters:
port The handle of a port to set the description of.
pPortName Pointer to a string containing the port description.
Returns:
One of the Error codes values.
Note:
  • the description string gets copied internally, and can be freed upon this function returns.
  • it's not possible to change the description of aggregating (BAP and T2AP) ports.

Thread safety: this function is thread safe if called on different ports. Calling this function on the same port from multiple threads concurrently can lead to unexpected results.

TC_PORT_TYPE TcPortGetType ( TC_PORT  port  ) 

It returns the type of a given port.

Parameters:
port The handle of a port to query for the type.
Returns:
One of the values in TC_PORT_TYPE

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortQueryMacAddress ( TC_PORT  port,
BYTE  pMac[6] 
)

It queries a port for the MAC address.

Parameters:
port The handle of a port to query for the MAC address
pMac A caller allocated array of at least 6 bytes to hold the MAC address of the port.
Returns:
One of the Error codes values.
Note:
It's possible to query the MAC address of physical ports, only. Querying the MAC address of a BAP or TcAP port will result in a TC_ERROR_INVALID_REQUEST error.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortQueryAggregatedPortList ( TC_PORT  aggregatingPort,
PTC_PORT ppPorts,
PULONG  pLength 
)

It queries an aggregating port for the list of physical ports that it aggregates.

Parameters:
aggregatingPort The handle of a port to query.
ppPorts Address of a caller allocated pointer to a TC_PORT. On success, the pointer will point to an array of port handles aggregated by the port. The returned list must not be freed.
pLength Address of a caller allocated unsigned long. On success, it contains the number of entries in the array of port handles ppPorts.
Returns:
One of the Error codes values.
Note:
  • It's possible to query aggregating ports (BAP and TcAP), only. Querying physical ports will result in a TC_ERROR_INVALID_REQUEST error.
  • The returned list must not be freed.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

BOOLEAN TcPortIsEqual ( TC_PORT  portA,
TC_PORT  portB 
)

It compares two port handles to check if they correspond to the same port.

Parameters:
portA Handle to the first port
portB Handle to the second port
Returns:
TRUE if the two port handles correspond to the same port (being it physical or aggregating).

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortQueryLinkStatus ( TC_PORT  port,
PTC_LINK_INFO  pLinkInfo 
)

Queries a port for the link status.

Parameters:
port Handle to the port to query.
pLinkInfo Pointer to a caller allocated TC_LINK_INFO structure. On success it contains the status of the link of the port.
Returns:
One of the Error codes values.
Note:
It's possible to query the link status of physical ports, only. Querying a BAP or TcAP port will result in a TC_ERROR_INVALID_REQUEST error.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortQueryStatistics ( TC_PORT  port,
PTC_STATISTICS  pStatistics 
)

It queries the statistics of a physical port.

Parameters:
port Port handle
pStatistics Pointer to a caller allocated statistics handle. On success it will return a valid statistics handle. In case of success, the returned statistics handle should be released with TcStatisticsDestroy.
Returns:
One of the Error codes values.
Note:
It's not possible to query the statistics of a virtual port.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortSetFeature ( TC_PORT  port,
ULONG  feature,
ULONG  value 
)

It sets a specific feature on the port.

Parameters:
port Port handle
feature Identifier of the feature. A list of the available features can be found in section Features.
value Value of the feature to be set. Please refer to the documentation of the specific feature you are trying to set in section Features.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortQueryFeature ( TC_PORT  port,
ULONG  feature,
PULONG  pValue 
)

It queries a specific feature on the port.

Parameters:
port Port handle
feature Identifier of the feature. A list of the available features can be found in section Features.
pValue Pointer to a 32bit integer. On success it will return the value of the feature. Please refer to the documentation in section Features to know what values can be returned by querying a specific feature.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe i.e. it can be called from multiple threads concurrently.

TC_STATUS TcPortSetAutonegotiationParameters ( TC_PORT  port,
TC_AUTONEG_PARAMETERS  autonegParameters 
)

It sets the autonegotiation parameters of a physical port i.e. it enables/disables autonegotiation and controls which link speeds should be advertised during autonegotiation.

Parameters:
port Handle to a physical port.
autonegParameters Parameters to enable/disable autonegotiation, set the advertised link speeds or force a link speed. Please refer to the documentation of TC_AUTONEG_PARAMETERS for details on autonegotiation.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe if called on different port handles (TC_PORT). Calling this function on the same port from concurrent threads yields undefined results.

Note:
It's possible to set the autonegotiation parameters of physical ports, only. Calling this function on a BAP or TcAP port will result in a TC_ERROR_INVALID_REQUEST error.
TC_STATUS TcPortQueryAutonegotiationParameters ( TC_PORT  port,
PTC_AUTONEG_PARAMETERS  pAutonegParameters 
)

It queries the autonegotiation parameters of a port i.e. if autonegotiation is enabled, which link speed be advertised during autonegotiation and which link speeds are supported by the port.

Parameters:
port Handle to a physical port.
pAutonegParameters Address of a caller allocated TC_AUTONEG_PARAMETERS structure. On success it contain the current autonegotiation parameters. Please refer to the documentation of TC_AUTONEG_PARAMETERS for details on autonegotiation.
Returns:
One of the Error codes values.

Thread safety: this function is thread safe if called on different port handles (TC_PORT). Calling this function on the same port from concurrent threads yields undefined results.

Note:
It's possible to query the autonegotiation parameters of physical ports, only. Calling this function on a BAP or TcAP port will result in a TC_ERROR_INVALID_REQUEST error.

TurboCap API documentation. Copyright (c) 2007-2008 CACE Technologies. All rights reserved.