> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QRTR APIs

> Kernel port lifecycle, service discovery, message transfer, and socket access.

The kernel API models a QRTR endpoint as a port. A client creates a port, resolves a service when necessary, sends and receives messages, and closes the port. A server additionally registers and unregisters a service name.

## Port lifecycle

A port goes through these stages:

1. **Create** – Create a port and supply a callback to be notified of events (data available, write completed, port state changed).
2. **Register (optional)** – If the port serves a service, register the service name so clients can find it.
3. **Ready** – Send and receive messages, or look up remote services.
4. **Unregister (optional)** – If the port was registered as a service, unregister it when the service stops.
5. **Close** – Close the port and clean up resources.

## Kernel-space interface

The kernel provides functions to create and manage ports:

* **Create a port** – Supply a callback function that will be called when events occur (data available, write completed, port state changed). The callback receives a private context pointer so the port can be associated with its owning driver state.
* **Send a message** – Specify a destination (either a service name or an endpoint address) and the data to send.
* **Receive a message** – Wait for a message to arrive, with an optional timeout. The receive function returns the payload and the source address.
* **Register a service** – Register a service name against the port so clients can look it up.
* **Unregister a service** – Unregister the service name when the service stops.
* **Close the port** – Close the port and release resources.

## Service registration and lookup

A server registers a service name against its local port. A client calls a lookup function when it has a service name but not the current endpoint address. The returned address can change when the service restarts or moves, so lookup failure and stale-address errors must be handled by the client.

## User-space sockets

User-space applications access the router through a message-oriented socket interface. The socket lifecycle follows the same model as the kernel API:

1. Create a socket
2. Bind to a local address or discover a remote service
3. Send and receive messages
4. Close the socket

Datagram boundaries are preserved as message boundaries, so the application should size receive buffers for the messages it expects to accept.

## API Reference

### Port lifecycle functions

These functions manage the lifecycle of a QRTR port:

* `qrtr_endpoint_create(const char *xprt_name, uint32_t port_id, qrtr_rx_cb rx_cb, void *priv)` – Create a port and register a callback to be notified of events (data available, write completed, port state changed).

* `qrtr_sendto(uint32_t node_id, uint32_t port_id, const void *data, size_t len)` – Send a message to a destination specified by node ID and port ID.

* `qrtr_send_to_service(uint32_t service_id, uint32_t instance_id, const void *data, size_t len)` – Send a message to a destination specified by service name (service ID and instance ID).

* `qrtr_recvfrom(uint32_t *node_id, uint32_t *port_id, void *data, size_t len, int timeout_ms)` – Wait for a message to arrive with optional timeout. Returns the payload and source address.

* `qrtr_publish(uint32_t service_id, uint32_t instance_id, uint32_t version)` – Register a service name against the port so clients can discover it.

* `qrtr_unpublish(uint32_t service_id, uint32_t instance_id)` – Unregister the service name when the service stops.

* `qrtr_endpoint_release(uint32_t port_id)` – Close the port and release all associated resources.

### Service discovery functions

* `qrtr_lookup_service(uint32_t service_id, uint32_t instance_id, uint32_t *node_id, uint32_t *port_id)` – Query the router for a service by name. Returns the endpoint address (node ID and port ID) of the service.

* `qrtr_get_service_list(uint32_t service_id, struct qrtr_service_info *services, size_t num_services, size_t *num_returned)` – Retrieve all available services matching a service ID.

### Socket interface functions

User-space applications use standard socket operations:

* `socket(AF_QIPCRTR, SOCK_DGRAM, 0)` – Create a message-oriented socket for QRTR communication.

* `bind(sockfd, (struct sockaddr *)&addr, sizeof(addr))` – Bind the socket to a local address or discover a remote service by name.

* `sendto(sockfd, data, len, 0, (struct sockaddr *)&dest_addr, sizeof(dest_addr))` – Send a message to a destination.

* `recvfrom(sockfd, data, len, 0, (struct sockaddr *)&src_addr, &addr_len)` – Receive a message from the socket.

* `close(sockfd)` – Close the socket and release resources.