gRPC API differences from C APIs

See also: General API Differences

Calculating output array size

A few functions take in additional parameters to calculate the output array size. 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 samples_per_signal and number_of_signals are added. Internally the output array size is calculated as (samples_per_signals * number_of_signals).

Functions with 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 example, APIs that accept or return Frame object as void* instead return a FrameBuffer message which uses oneof to return a frame based on the API used to read 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;
        }

• Get/Set Property 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 void* parameters which accept 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

nxGetLastError is not exposed in gRPC. Instead, 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;
}

Bitfield changes in ReadState API

• The ReadState API returns a structured message instead of returning a void* message. While the ReadState API returns a u32 value containing bitfields for several pieces of information, the gRPC response contains these bitfields in separate parts of the message. For example, when reading nxState_CANComm, gRPC returns the following 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;
    }