sjanc commented on code in PR #1530:
URL: https://github.com/apache/mynewt-nimble/pull/1530#discussion_r1265615767
##########
nimble/host/include/host/ble_l2cap.h:
##########
@@ -234,33 +470,166 @@ struct ble_l2cap_event {
};
};
+/**
+ * @brief Represents information about an L2CAP channel.
+ *
+ * This structure is typically used to retrieve or provide information about
an existing L2CAP channel.
+ */
struct ble_l2cap_chan_info {
+ /** Source Channel Identifier. */
uint16_t scid;
+
+ /** Destination Channel Identifier. */
uint16_t dcid;
+
+ /** Local L2CAP Maximum Transmission Unit. */
uint16_t our_l2cap_mtu;
+
+ /** Peer L2CAP Maximum Transmission Unit. */
uint16_t peer_l2cap_mtu;
+
+ /** Protocol/Service Multiplexer of the channel. */
uint16_t psm;
+
+ /** Local CoC Maximum Transmission Unit. */
uint16_t our_coc_mtu;
+
+ /** Peer CoC Maximum Transmission Unit. */
uint16_t peer_coc_mtu;
};
+/**
+ * @brief Function pointer type for handling L2CAP events.
+ *
+ * @param event A pointer to the L2CAP event structure.
+ * @param arg A pointer to additional arguments passed to the callback
function.
+ *
+ * @return Integer value representing the status or result of the
event handling.
+ */
typedef int ble_l2cap_event_fn(struct ble_l2cap_event *event, void *arg);
-
+/**
+ * @brief Get the connection handle associated with an L2CAP channel.
+ *
+ * This function retrieves the connection handle associated with the specified
L2CAP channel.
+ *
+ * @param chan A pointer to the L2CAP channel structure.
+ *
+ * @return The connection handle associated with the L2CAP channel on
success;
+ * A Bluetooth Host Error Code on failure:
+ * BLE_HS_CONN_HANDLE_NONE: if the provided channel pointer
is NULL.
+ */
uint16_t ble_l2cap_get_conn_handle(struct ble_l2cap_chan *chan);
+
+/**
+ * @brief Create an L2CAP server.
+ *
+ * This function creates an L2CAP server with the specified Protocol/Service
Multiplexer (PSM) and Maximum
+ * Transmission Unit (MTU) size. The server is used to accept incoming L2CAP
connections from remote clients.
+ * When a connection request is received, the provided callback function will
be invoked with the corresponding
+ * event information.
+ *
+ * @param psm The Protocol/Service Multiplexer (PSM) for the server.
+ * @param mtu The Maximum Transmission Unit (MTU) size for the server.
+ * @param cb Pointer to the callback function to be invoked when a
connection request is received.
+ * @param cb_arg An optional argument to be passed to the callback function.
+ *
+ * @return 0 on success;
+ * A non-zero value on failure.
+ */
int ble_l2cap_create_server(uint16_t psm, uint16_t mtu,
ble_l2cap_event_fn *cb, void *cb_arg);
+/**
+ * @brief Initiate an L2CAP connection.
+ *
+ * This function initiates an L2CAP connection to a remote device with the
specified connection handle,
+ * Protocol/Service Multiplexer (PSM), Maximum Transmission Unit (MTU) size,
and receive SDU buffer.
+ * When the connection is established or if there is an error during the
connection process, the provided
+ * callback function will be invoked with the corresponding event information.
+ *
+ * @param conn_handle The connection handle for the remote device.
+ * @param psm The Protocol/Service Multiplexer (PSM) for the
connection.
+ * @param mtu The Maximum Transmission Unit (MTU) size for the
connection.
+ * @param sdu_rx Pointer to the receive Service Data Unit (SDU) buffer.
+ * @param cb Pointer to the callback function to be invoked when
the connection is established.
+ * @param cb_arg An optional argument to be passed to the callback
function.
+ *
+ * @return 0 on success;
+ * A non-zero value on failure.
+ */
int ble_l2cap_connect(uint16_t conn_handle, uint16_t psm, uint16_t mtu,
struct os_mbuf *sdu_rx,
ble_l2cap_event_fn *cb, void *cb_arg);
+
+/**
+ * @brief Disconnect an L2CAP channel.
+ *
+ * This function disconnects the specified L2CAP channel by sending a
disconnect signal.
+ *
+ * @param chan Pointer to the L2CAP channel structure representing
the channel to disconnect.
+ *
+ * @return 0 on success;
+ * A non-zero value on failure.
+ */
int ble_l2cap_disconnect(struct ble_l2cap_chan *chan);
+
+/**
+ * @brief Send an SDU (Service Data Unit) over an L2CAP channel.
+ *
+ * This function sends an SDU over the specified L2CAP channel. The SDU is
encapsulated
+ * in L2CAP frames and transmitted to the remote device.
+ *
+ * @param chan Pointer to the L2CAP channel structure representing
the channel to send the SDU on.
+ * @param sdu_tx Pointer to the os_mbuf structure containing the SDU
(Service Data Unit) to send.
+ *
+ * @return 0 on success;
+ * BLE_HS_ESTALLED: if the transmit buffer contained an
SDU that has not been entirely sent,
Review Comment:
this is not correct, host will return ESTALLED when there was not enough
credits available to send whole SDU, in such case application needs to wait
for BLE_L2CAP_EVENT_COC_TX_UNSTALLED event before being able to transmit more
data
(and BLE_L2CAP_COC_FLAG_STALLED is implementation internal detail, no need
to mentioned it here)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: commits-unsubscr...@mynewt.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
