aboutsummaryrefslogtreecommitdiffstats
path: root/o3000.c
diff options
context:
space:
mode:
authorjonas <schmid@stettbacher.ch>2020-10-06 08:57:40 +0200
committerjonas <schmid@stettbacher.ch>2020-10-06 08:57:40 +0200
commitee0607b8a7ff7eb755d32719c4bd7b6920447c1f (patch)
treebe1d55b244e130e487aaa78905ae729118d9be99 /o3000.c
parentdistinguish between 32 or 64 bit compiler version (diff)
downloado3000-driver-ee0607b8a7ff7eb755d32719c4bd7b6920447c1f.tar.gz
o3000-driver-ee0607b8a7ff7eb755d32719c4bd7b6920447c1f.zip
"Dogxygen style" function commenting.
Diffstat (limited to 'o3000.c')
-rw-r--r--o3000.c42
1 files changed, 21 insertions, 21 deletions
diff --git a/o3000.c b/o3000.c
index dd99f97..31d1adc 100644
--- a/o3000.c
+++ b/o3000.c
@@ -60,22 +60,22 @@ Two groups of functions represent the interface:
The basic approach using the camera driver is:
<ol>
<li> Implementing all required callback functions, see @ref cb_fun. </li>
-<li> Initialising the camera driver, see o3000_init(). </li>
-<li> Connecting to the camera driver, see o3000_connect(). </li>
+<li> Initialising the camera driver, see @ref o3000_init. </li>
+<li> Connecting to the camera driver, see @ref o3000_connect. </li>
</ol>
-Once the user application is connected to the driver by calling o3000_connect(), it will block until:
+Once the user application is connected to the driver by calling @ref o3000_connect, it will block until:
<ul>
-<li> The driver exits by calling o3000_exit(). </li>
+<li> The driver exits by calling @ref o3000_exit. </li>
<li> The camera is disconnected from the system. </li>
</ul>
-XML messages are transfered to the camera by calling o3000_send_xml(). If the camera sends a XML message to the host, the
+XML messages are transfered to the camera by calling @ref o3000_send_xml. If the camera sends a XML message to the host, the
driver triggers the @ref xml_cb. The same concept is used, when the camera sends video data to the host. After receving a complete frame, the driver calls the
@ref video_cb.
-@note The video driver triggers any callback from the thread context, where o3000_connect() is called from. This means that the o3000_send_xml() function should
-never be called from the Video, XML or Logging callback. Otherwise the driver will lock. It's important, that any XML message sent with o3000_send_xml() to the camera
+@note The video driver triggers any callback from the thread context, where @ref o3000_connect is called from. This means that the @ref o3000_send_xml function should
+never be called from the Video, XML or Logging callback. Otherwise the driver will lock. It's important, that any XML message sent with @ref o3000_send_xml to the camera
is called from a different thread context.
@@ -107,7 +107,7 @@ containing the log message. This handler is optional.
A simplified example with C is shown below, focussing on the order in which the various
camera driver functions should be called. It's up to the user to implement
-multithreading in order to avoid a deadlock due to the blocking nature of o3000_connect()!
+multithreading in order to avoid a deadlock due to the blocking nature of @ref o3000_connect!
@code
@@ -828,7 +828,7 @@ static int send_xml(struct o3000_session_t *session, const char *msg, int msg_le
/**
* Send XML packet from host to device.
*
- * @note Never call this function from the thread context o3000_connect() is called from!
+ * @note Never call this function from the thread context @ref o3000_connect is called from!
*
* @param id session ID
* @param msg message content
@@ -870,9 +870,9 @@ int __stdcall o3000_send_xml(int id, const char *msg, int msg_len) {
/**
* Disconnect a currently claimed USB connection.
- * Use this function if the driver is connected to an USB device. The o3000_connect() function-call is blocking now.
- * After disconnecting, the function o3000_connect() returns. The session is not cleaned-up due to the driver is ready the reconnect
- * to the same USB device by calling o3000_connect() again.
+ * Use this function if the driver is connected to an USB device. The @ref o3000_connect function-call is blocking now.
+ * After disconnecting, the function @ref o3000_connect returns. The session is not cleaned-up due to the driver is ready the reconnect
+ * to the same USB device by calling @ref o3000_connect again.
*
* @param id session ID
* @return 0 on success, or error code defined at @ref o3000.h.
@@ -913,16 +913,16 @@ int __stdcall o3000_disconnect(int id) {
/**
* Estabslish a connection to an existing device.
* If several devices are available on the same system, the device number is used. The number of devices are requested
- * by o3000_get_num_device().
+ * by @ref o3000_get_num_device.
*
* NOTE
- * This function will block until the USB device is disconnected manually or the driver is stopped by calling o3000_exit().
+ * This function will block until the USB device is disconnected manually or the driver is stopped by calling @ref o3000_exit.
*
* @param id session ID
* @param device_nr device number to connect (use 0 to connect to first available device)
* @param config_msg configuration message to be sent to device after successful connection, or NULL if not used
* @param config_msg_len configuration message length
- * @return 0 is returned only after calling dmm_exit() or dmm_disconnect(). Otherwise the error code defined at @ref o3000.h.
+ * @return 0 is returned only after calling @ref dmm_exit or @ref dmm_disconnect. Otherwise the error code defined at @ref o3000.h.
*/
int __stdcall o3000_connect(int id, int device_nr, char *config_msg, int config_msg_len) {
@@ -1052,12 +1052,12 @@ int __stdcall o3000_connect(int id, int device_nr, char *config_msg, int config_
/*
* There are following reasons to get here:
*
- * 1. o3000_disconnect() was called
- * 2. o3000_exit() was called
+ * 1. o3000_disconnect was called
+ * 2. o3000_exit was called
* 3. the device isn't available anymore because it was unplugged, it does an USB hardware reset
*
- * The current session is cleaned-up only if o3000_exit() has been called. Otherwise the session will further exist and a reconnection with o3000_connect() will be allowed.
- * Actually, it doesn't make any sense to connect to an unavailable device. But to keep it simple, a session is cleaned-up only with o3000_exit() without any exception.
+ * The current session is cleaned-up only if o3000_exit has been called. Otherwise the session will further exist and a reconnection with o3000_connect will be allowed.
+ * Actually, it doesn't make any sense to connect to an unavailable device. But to keep it simple, a session is cleaned-up only with o3000_exit without any exception.
*/
if(session->release_session == FALSE && session->disconnect_dev == FALSE) {
// device was unplugged (see reason 3 few lines above)
@@ -1076,7 +1076,7 @@ int __stdcall o3000_connect(int id, int device_nr, char *config_msg, int config_
session->dev = NULL;
}
- // release session due to o3000_exit() call
+ // release session due to o3000_exit call
if(session->release_session == TRUE) {
o3000_log(session, O3000_LOG_DEBUG, "%s: cleanup session\n", __func__);
session->release_session = FALSE;
@@ -1098,7 +1098,7 @@ _connect_abort:
/**
* The device discovery returns the number of USB devices in question.
* In fact, the number of devices with the session PID/VID are counted. After knowing the number of devices, any connection can be
- * established with o3000_connect().
+ * established with @ref o3000_connect.
*
* @param id valid session ID
* @return number of USB device or a negative return code