gRPC API differences from C APIs

See also: General API Differences

Signal Functions

For the gRPC API to internally calculate the output array size, it is provided with few additional parameters. For example, the gRPC API definition for ReadSignalWaveform is

message ReadSignalWaveformRequest {
  nidevice_grpc.Session session = 1;
  oneof timeout_enum {
    TimeOut timeout = 2;
    double timeout_raw = 3;
  }
  uint32 samples_per_signal = 4;
  uint32 number_of_signals = 5;
}

Here two new parameters are added which are samples_per_signal and number_of_signals because the client already knows the number of signals in the session and samples_per_signal indicates the number of samples per signal user wants in the output array. Internally the gRPC API calculates the output array size as (samples_per_signals * number_of_signals) and allocates the output array with this value.

Similar thing is applicable to the following signal APIs

• ReadSignalSinglePoint
• ReadSignalXY
• ConvertFramesToSignalsSinglePoint

Functions void* parameters

• All APIs that accept or return void* have been updated in gRPC to return structured message with separate fields in message for each piece of information. For e.g. APIs that accept or return Frame object as void* instead return a FrameBuffer message which uses oneof to return frame based on interface being used for reading the frame. The FrameBuffer message looks like

        message FrameBufferRequest {
            oneof frame {
                FrameRequest can = 1;
                FrameRequest lin = 2;
                FrameRequest flex_ray = 3;
                FrameRequest j1939 = 4;
                EnetFrameRequest enet = 5;
            }
        }

Each Frame* message contains fields appropriate for specific frame.

        message FrameRequest {
            uint64 timestamp = 1;
            uint32 identifier = 2;
            oneof type_enum{
                FrameType type = 3;
                uint32 type_raw = 4;
            }
            repeated FrameFlags flags = 5;
            uint32 info = 6;
            bytes payload = 7;
        }

• ReadState/WriteState APIs have been modified on similar lines to return structured message instead of returning void* messages. In ReadState/WriteState API where return value is u32 containing bitfields for several pieces of information, gRPC response contains these bitfields in separate fields of the message. For e.g. if want to read nxState_CANComm, instead of return u32 value like C API, gRPC API return below message.

    message CanCommResponse {
        CanCommState comm_state = 1;
        uint32 comm_state_raw = 2;
        uint32 transceiver_error = 3;
        uint32 sleep = 4;
        CanLastErr last_error = 5;
        uint32 last_error_raw = 6;
        uint32 transmit_error_counter = 7;
        uint32 receive_error_counter = 8;
    }

• Get/Set APIs have also been modified on similar lines. Based on datatypes of different PropertyIDs, oneof fields are used in request/response message. For example

    message GetPropertyResponse {
        int32 status = 1;
        oneof property_value {
            uint32 u32_scalar = 2;
            bool bool_scalar = 3;
            string str = 4;
            uint64 u64_scalar = 5;
            int32 i32_scalar = 6;
            double f64_scalar = 7;
            string string_array = 8;
            U32Array u32_array = 9;
            nidevice_grpc.Session db_ref = 10;
            DbRefArray db_ref_array = 11;
            nidevice_grpc.Session dev_ref = 12;
            DeviceRefArray dev_ref_array = 13;
            InterfaceRefArray intf_ref_array = 14;
            EptRxFilterArray ept_rx_filter_array = 15;
        }
    }

• For the void* parameters which accepts structs in C Socket APIs, the gRPC equivalent has been implemented with oneof or union types. For example

    message SockAddr {
        oneof addr {
            SockAddrIn ipv4 = 1;
            SockAddrIn6 ipv6 = 2;
        }
    }

Error reporting in Socket APIs

Each gRPC Socket API has been added with parameters for getting Error number and Error message. For example

message AcceptResponse {
  int32 status = 1;
  SockAddr addr = 2;
  nidevice_grpc.Session socket = 3;
  string error_message = 4;
  int32 error_num = 5;
}