| Affix - Technical Documentation: Affix - Open Source Bluetooth Protocol Stack for Linux | ||
|---|---|---|
| Prev | Chapter 3. Application Programming Interface | Next |
The Affix provides a flexible API to implement OBEX server and OBEX client applications. The OBEX API is very simple. Any object is stored in a file before/after transfer. The Affix OBEX API provides easy way to deal with it.
All data structure definitions are located in the <affix/obex.h> header file and they include: obexclt_t, obexsrv_t, obex_file_t.
The main concept of the Affix OBEX API is that before object can be transferred it must be stored in a file. Affix has a following function set for that:
Table 3-18. OBEX file API
| Function | Purpose |
|---|---|
| obex_file_t *obex_create_file(char *name); | Creates file object from a file "name". If "name" is NULL then it creates a file with randomly generated name. |
| void obex_close_file(obex_file_t *file); | Closes file. |
| int obex_open_file(obex_file_t *file); | Reopens a file referenced by the file object "file". |
| void obex_destroy_file(obex_file_t *file, int del); | Closes file and destroys file object. If "del" is not zero then file is removed. |
| char *obex_map_file(obex_file_t *file); | Maps file referenced by file object "file" to memory location and returns pointer to that. |
The OBEX client API includes two sets of functions: general purpose and file transfer oriented.
Table 3-19. OBEX client API
| Function | Purpose |
|---|---|
| obexclt_t *obex_connect(struct sockaddr_affix *addr, obex_target_t *target, int *err); | Opens connection to OBEX server. Accepts sockaddr_affix address and target. Reruns OBEX client object. |
| int obex_disconnect(obexclt_t *clt); | Closes connection to OBEX server. |
| int obex_get(obexclt_t *clt, char *local, char *remote, char *type); | Receives object from the server. Target object specified by "remote" and "type" arguments. It is stored in the file "local". |
| int obex_put(obexclt_t *clt, char *local, char *remote, char *type); | Sends object from a file "local" to the server. Target object identified by "remote" and "type". |
| obexclt_t *obex_connect_file(struct sockaddr_affix *addr, int *err); | Opens connection to FTP service on the server. |
| int obex_get_file(obexclt_t *clt, char *local, char *remote); | Receives file "remote" from the server and stores it to the file "local". If "local" is NULL then file is stored with the name "remote" to the current working directory. |
| int obex_put_file(obexclt_t *clt, char *local, char *remote); | Sends file "local" to the server and stores it in the file "remote". If "remote" is NULL then file is stored with the name "local" to the server current working directory. |
| int obex_browse(obexclt_t *clt, char *local, char *name); | Gets "name" folder listing from the server and stores it in the file local. |
| int obex_setpath(obexclt_t *clt, char *path); | Changes working directory on the server to "path". |
| int obex_mkdir(obexclt_t *clt, char *path); | Creates new directory with path "path" on the server. |
The Affix provides a very simple API to implement OBEX servers also. OBEX server works in request-response way: waits for a request from client, processes it and sends response back.
The main idea behind API is "call-back" function. OBEX server exports certain functions, which are called by the Affix OBEX library when certain request arrives. Server implementation has to create a server object and initialize callback function pointers (see bellow) and to call btsrv_run() to start request processing loop.
Table 3-20. OBEX server API
| Function | Purpose |
|---|---|
| int obexsrv_run(obexsrv_t *srv, int rfd, int wfd); | Starts server's main request processing loop. It reads request from the endpoint referenced by the file descriptor "rfd" and writes responses to the endpoint referenced by the file descriptor "wfd". |
| int (*connect)(obexsrv_t *srv, obex_target_t *target); | Function is called on connection request. "target" points to "connection target". |
| void (*disconnect)(obexsrv_t *srv); | Function is called on disconnection. |
| int (*put)(obexsrv_t *srv, char *file, char *name, char *type, int flags); | Function is called on PUT request. File "file" contains object. The object identified by "name" and "type" on the server. |
| int (*get)(obexsrv_t *srv, char *name, char *type); | Function is called on GET request. An Object identified by "name" and "type". |
| int (*setpath)(obexsrv_t *srv, char *path, int flags); | Function is called on SETPATH request. "path" points to path to set. |
| void obexsrv_set_file(obexsrv_t *srv, char *name, int del); | Sets a file to be transferred on GET request. (usually is used in get() callback function) |