c-cursor-no-gen

Example: Tasks

This example shows how to use the ObjectBox C API to create a simple console-based task-list application.

To add a new task, simply enter the task text as arguments:

./objectbox-c-examples-tasks Buy milk

Now you can run ./objectbox-c-examples-tasks without arguments to see the list of open tasks:

ID  Created              Finished             Text
 1  2018-09-10 12:44:07                       Buy milk

To complete a task, you would run ./objectbox-c-examples-tasks --done 1 (1 is the ID of the task as shown above). And to show all complete tasks you can run ./objectbox-c-examples-tasks --done.

Code overview

Files:

• main.c: actual example code
• task.fbs: FlatBuffers schema file to define a table "Task" with its properties
• Other files are auto-generated by flatcc

Code organization

1. In the main() parses arguments and sets up ObjectBox store based on a data model
2. Start a transaction and get a cursor for the Task entity type
3. Execute a requested action using the cursor
4. Gracefully close everything and clean it up

The following methods demonstrate some of the API capabilities:

• task_list() - iterates over the whole dataset
• task_create() - insert (calls task_put())
• task_done() - select & update (calls task_put())
• task_put() - actual insert/update (overwrite) - builds flatbuffer and writes it to the store.

Changing the data model

For convenience, all FlatBuffer files for the Task entity are already generated.

You may want to change the data model to expend the example or to start your own data model for a new app. Here's what you have to do:

1. Edit task.fbs
2. Generate FlatBuffers sources again using flatcc and the script ./flatcc-fbs.sh. For the script to work, you need flatcc in the $PATH (or update the script with the file path of your compiled bin/flatcc).
3. Once the FlatBuffers model is changed, you need to adjust the ObjectBox model accordingly: The model defined in the model_create() method and in the task.fbs file should be kept in sync.

Some quick notes on IDs and UIDs in the ObjectBox model:

• Entity IDs need to be unique among themselves
• Property IDs need to be unique inside their Entity
• All UIDs need to be unique application-wide
• See Meta Model, IDs, and UIDs docs for more details.

Note: We are using flatbuffers auxiliary methods to build the Task data. See Flatcc & FlatBuffers documentation for more details.

Command line options

Run objectbox-c-examples-tasks --help to see available options for the example application. The output looks like this:

usage: objectbox-c-examples-tasks 
    text of a new task             create a new task with the given text
                                   (default) lists active tasks
    --done                         lists active and done tasks
    --done ID                      marks the task with the given ID as done
    --help                         displays this help

License

Copyright 2018 ObjectBox Ltd. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.