Skip to main content

​
SecurityLocalRegisterApplicationProtocol

CAPL Functions » Security » SecurityLocalRegisterApplicationProtocol Valid for: CANoe DE • CANoe4SW DE

​
Function Syntax

  • long SecurityLocalRegisterApplicationProtocol(char applicationProtocolUserDefinedId[]) // form 1
  • long SecurityLocalRegisterApplicationProtocol(char applicationProtocolUserDefinedId[], dword vLanId) // form 2

​
Description

Registers the reception of the application protocol with the specified User Defined Id. The node will receive this application protocol as soon as it is transmitted on the network and the callbacks OnSecurityLocalApplicationProtocolRxFinished or OnSecurityLocalApplicationProtocolTxFinished will also be called accordingly. The call of SecurityLocalAllowNetworkWideRegistrations is a precondition for using this function.

​
Parameters

  • char applicationProtocolUserDefinedId[]
    Name of the Application Protocol to register for (form 1 and form 2).
  • dword vLanId
    In case of Ethernet networks, the VLAN has to be specified as well.

​
Return Values

  • 1: Success
  • -1: The specified applicationProtocolUserDefinedId has already been registered.
  • -2: SecurityLocalAllowNetworkWideRegistrations must be called before using this function.
  • -3: The specified applicationProtocolUserDefinedId does not exist. Please check the definition in the used Security Profile.
  • -4: The applicationProtocol for the specified UserDefinedId exist but is not available on this network.
  • -5: The specified applicationProtocolUserDefinedId has already been registered on the same VLAN.
  • -6: The Security Manager does not support this function. (Security Manager V2.3.9 or later required).
  • -10: Security is not usable. Reasons can be: Security Manager version is too old. Tool Version is too old. Security Profile is invalid.

​
Example

// Implement this in an Observer-Node to receive callbacks of Application-Protocol for real ECUs
on preStart
{
  long result = 0;
  result = SecurityLocalAllowNetworkWideRegistrations();
  Write("The call of SecurityLocalAllowNetworkWideRegistrations returned %i", result);
}

on start
{
  dword result = 0;
  result = SecurityLocalRegisterApplicationProtocol("APPLICATIONPROTOCOLNAME",10);
  Write("SecurityLocalRegisterApplicationProtocol to register to APPLICATIONPROTOCOLNAME on VLAN 10 returned %i", result);
}

void OnLocalSecurityApplicationProtocolRxFinished(char applicationProtocolName[], byte payload[], dword payloadLength, dword result)
{
  if(strncmp(applicationProtocolName,"APPLICATIONPROTOCOLNAME",23) == 0)
  {
    write("Received Application Protocol %s", applicationProtocolName);
  }
}

on stopMeasurement
{
  dword result = 0;
  result = SecurityLocalUnregisterApplicationProtocol("APPLICATIONPROTOCOLNAME",10);
  Write("SecurityLocalUnregisterApplicationProtocol to unregister from APPLICATIONPROTOCOLNAME on VLAN 10 returned %i", result);
}