0
# Logging
1

2
Error reporting, debug logging, and message handling system for libdc1394.
3

4
## Capabilities
5

6
### Log Message Functions
7

8
Built-in logging functions for error reporting and debugging.
9

10
```java { .api }
11
/**
12
 * Logs an error message
13
 * @param format Error message string
14
 */
15
void dc1394_log_error(String format);
16

17
/**
18
 * Logs a warning message  
19
 * @param format Warning message string
20
 */
21
void dc1394_log_warning(String format);
22

23
/**
24
 * Logs a debug message
25
 * @param format Debug message string
26
 */
27
void dc1394_log_debug(String format);
28
```
29

30
**Usage Example:**
31

32
```java
33
import org.bytedeco.libdc1394.*;
34
import static org.bytedeco.libdc1394.global.dc1394.*;
35

36
// Basic logging usage
37
dc1394_log_error("Camera initialization failed");
38
dc1394_log_warning("Using default video mode");
39
dc1394_log_debug("Frame capture completed successfully");
40

41
// Logging with context information
42
dc1394_log_error("Failed to set video mode " + video_mode + " for camera " + 
43
                 Long.toHexString(camera.guid()));
44
dc1394_log_warning("Camera " + camera.model() + " does not support feature " + feature);
45
dc1394_log_debug("Captured frame " + frame_count + " at timestamp " + timestamp);
46
```
47

48
### Custom Log Handlers
49

50
Register custom log handlers to redirect log messages to your application's logging system.
51

52
```java { .api }
53
/**
54
 * Registers a custom log handler for specified log types
55
 * @param type Log level (DC1394_LOG_ERROR, DC1394_LOG_WARNING, DC1394_LOG_DEBUG)
56
 * @param log_handler Custom handler function
57
 * @param user User data passed to handler
58
 * @return DC1394_SUCCESS on success, error code on failure
59
 */
60
int dc1394_log_register_handler(int type, Log_handler_int_BytePointer_Pointer log_handler, 
61
                               Pointer user);
62

63
/**
64
 * Restores the default log handler for specified log type
65
 * @param type Log level to reset to default handler
66
 * @return DC1394_SUCCESS on success, error code on failure
67
 */
68
int dc1394_log_set_default_handler(int type);
69
```
70

71
**Usage Example:**
72

73
```java
74
import org.bytedeco.libdc1394.*;
75
import org.bytedeco.libdc1394.global.dc1394.*;
76
import org.bytedeco.javacpp.*;
77

78
// Custom log handler implementation
79
public class CustomLogHandler extends Log_handler_int_BytePointer_Pointer {
80
    @Override
81
    public void call(int type, BytePointer message, Pointer user) {
82
        String msg = message.getString();
83
        String level;
84
        
85
        switch (type) {
86
            case DC1394_LOG_ERROR:
87
                level = "ERROR";
88
                break;
89
            case DC1394_LOG_WARNING:
90
                level = "WARNING";  
91
                break;
92
            case DC1394_LOG_DEBUG:
93
                level = "DEBUG";
94
                break;
95
            default:
96
                level = "UNKNOWN";
97
                break;
98
        }
99
        
100
        // Forward to your application's logging system
101
        System.err.println("[libdc1394 " + level + "] " + msg);
102
        
103
        // Or use a more sophisticated logging framework
104
        // logger.log(convertLevel(type), msg);
105
    }
106
}
107

108
// Register custom handlers
109
CustomLogHandler handler = new CustomLogHandler();
110
dc1394_log_register_handler(DC1394_LOG_ERROR, handler, null);
111
dc1394_log_register_handler(DC1394_LOG_WARNING, handler, null);
112
dc1394_log_register_handler(DC1394_LOG_DEBUG, handler, null);
113

114
// Now all libdc1394 log messages will go through your custom handler
115
dc1394_log_error("This will be handled by custom handler");
116

117
// Restore default handler when needed
118
dc1394_log_set_default_handler(DC1394_LOG_ERROR);
119
```
120

121
### Advanced Logging Integration
122

123
Example showing integration with popular Java logging frameworks:
124

125
```java
126
import org.bytedeco.libdc1394.*;
127
import org.bytedeco.libdc1394.global.dc1394.*;
128
import org.bytedeco.javacpp.*;
129
import java.util.logging.Logger;
130
import java.util.logging.Level;
131

132
public class LoggingIntegration {
133
    private static final Logger logger = Logger.getLogger("libdc1394");
134
    
135
    // Log handler that integrates with java.util.logging
136
    public static class JULLogHandler extends Log_handler_int_BytePointer_Pointer {
137
        @Override
138
        public void call(int type, BytePointer message, Pointer user) {
139
            String msg = message.getString();
140
            Level level;
141
            
142
            switch (type) {
143
                case DC1394_LOG_ERROR:
144
                    level = Level.SEVERE;
145
                    break;
146
                case DC1394_LOG_WARNING:
147
                    level = Level.WARNING;
148
                    break;
149
                case DC1394_LOG_DEBUG:
150
                    level = Level.FINE;
151
                    break;
152
                default:
153
                    level = Level.INFO;
154
                    break;
155
            }
156
            
157
            logger.log(level, msg);
158
        }
159
    }
160
    
161
    // Log handler for SLF4J integration
162
    public static class SLF4JLogHandler extends Log_handler_int_BytePointer_Pointer {
163
        private final org.slf4j.Logger slf4jLogger = 
164
            org.slf4j.LoggerFactory.getLogger("libdc1394");
165
            
166
        @Override
167
        public void call(int type, BytePointer message, Pointer user) {
168
            String msg = message.getString();
169
            
170
            switch (type) {
171
                case DC1394_LOG_ERROR:
172
                    slf4jLogger.error(msg);
173
                    break;
174
                case DC1394_LOG_WARNING:
175
                    slf4jLogger.warn(msg);
176
                    break;
177
                case DC1394_LOG_DEBUG:
178
                    slf4jLogger.debug(msg);
179
                    break;
180
                default:
181
                    slf4jLogger.info(msg);
182
                    break;
183
            }
184
        }
185
    }
186
    
187
    public static void setupJavaUtilLogging() {
188
        JULLogHandler handler = new JULLogHandler();
189
        dc1394_log_register_handler(DC1394_LOG_ERROR, handler, null);
190
        dc1394_log_register_handler(DC1394_LOG_WARNING, handler, null);
191
        dc1394_log_register_handler(DC1394_LOG_DEBUG, handler, null);
192
    }
193
    
194
    public static void setupSLF4JLogging() {
195
        SLF4JLogHandler handler = new SLF4JLogHandler();  
196
        dc1394_log_register_handler(DC1394_LOG_ERROR, handler, null);
197
        dc1394_log_register_handler(DC1394_LOG_WARNING, handler, null);
198
        dc1394_log_register_handler(DC1394_LOG_DEBUG, handler, null);
199
    }
200
}
201
```
202

203
### Contextual Logging Helper
204

205
Create a helper class for more structured logging with context:
206

207
```java
208
import org.bytedeco.libdc1394.*;
209
import static org.bytedeco.libdc1394.global.dc1394.*;
210

211
public class DC1394Logger {
212
    private final String context;
213
    
214
    public DC1394Logger(String context) {
215
        this.context = context;
216
    }
217
    
218
    public void error(String message) {
219
        dc1394_log_error("[" + context + "] " + message);
220
    }
221
    
222
    public void error(String message, Exception e) {
223
        dc1394_log_error("[" + context + "] " + message + ": " + e.getMessage());
224
    }
225
    
226
    public void warning(String message) {
227
        dc1394_log_warning("[" + context + "] " + message);
228
    }
229
    
230
    public void debug(String message) {
231
        dc1394_log_debug("[" + context + "] " + message);
232
    }
233
    
234
    public void logResult(String operation, int result) {
235
        if (result == DC1394_SUCCESS) {
236
            debug(operation + " completed successfully");
237
        } else {
238
            BytePointer error_desc = dc1394_error_get_string(result);
239
            error(operation + " failed: " + error_desc.getString() + " (code: " + result + ")");
240
        }
241
    }
242
    
243
    public void logCameraInfo(dc1394camera_t camera) {
244
        debug("Camera info - GUID: " + Long.toHexString(camera.guid()) + 
245
              ", Model: " + camera.model() + 
246
              ", Vendor: " + camera.vendor());
247
    }
248
    
249
    public void logFrameInfo(dc1394video_frame_t frame) {
250
        debug("Frame info - Size: " + frame.size(0) + "x" + frame.size(1) + 
251
              ", Bytes: " + frame.image_bytes() + 
252
              ", Timestamp: " + frame.timestamp());
253
    }
254
}
255

256
// Usage example
257
public class CameraApplication {
258
    private final DC1394Logger logger = new DC1394Logger("CameraApp");
259
    
260
    public void initializeCamera() {
261
        dc1394_t d = dc1394_new();
262
        if (d == null) {
263
            logger.error("Failed to initialize libdc1394 context");
264
            return;
265
        }
266
        logger.debug("libdc1394 context created successfully");
267
        
268
        dc1394camera_list_t list = new dc1394camera_list_t();
269
        int err = dc1394_camera_enumerate(d, list);
270
        logger.logResult("Camera enumeration", err);
271
        
272
        if (err == DC1394_SUCCESS && list.num() > 0) {
273
            logger.debug("Found " + list.num() + " cameras");
274
            
275
            dc1394camera_t camera = dc1394_camera_new(d, list.ids().guid());
276
            if (camera != null) {
277
                logger.logCameraInfo(camera);
278
            } else {
279
                logger.error("Failed to create camera instance");
280
            }
281
        }
282
    }
283
}
284
```
285

286
## Log Levels and Constants
287

288
```java { .api }
289
// Log level constants
290
static final int DC1394_LOG_ERROR = 768;      // Error messages
291
static final int DC1394_LOG_WARNING = 769;    // Warning messages  
292
static final int DC1394_LOG_DEBUG = 770;      // Debug messages
293
```
294

295
## Best Practices
296

297
### Logging Strategy
298

299
1. **Use appropriate log levels:**
300
   - `ERROR`: Critical failures that prevent operation
301
   - `WARNING`: Issues that don't prevent operation but should be noted
302
   - `DEBUG`: Detailed information for troubleshooting
303

304
2. **Include context in messages:**
305
   ```java
306
   dc1394_log_error("Camera " + Long.toHexString(camera.guid()) + 
307
                    " failed to set mode " + video_mode);
308
   ```
309

310
3. **Log function results:**
311
   ```java
312
   int err = dc1394_video_set_mode(camera, video_mode);
313
   if (err != DC1394_SUCCESS) {
314
       dc1394_log_error("Video mode setting failed: " + 
315
                        dc1394_error_get_string(err).getString());
316
   }
317
   ```
318

319
### Performance Considerations
320

321
Debug logging can impact performance. Use conditional logging for high-frequency operations:
322

323
```java
324
private static final boolean DEBUG_ENABLED = 
325
    System.getProperty("dc1394.debug", "false").equals("true");
326

327
public void captureFrame() {
328
    // High-frequency operation
329
    int err = dc1394_capture_dequeue(camera, DC1394_CAPTURE_POLICY_WAIT, frame);
330
    
331
    if (DEBUG_ENABLED && err == DC1394_SUCCESS) {
332
        dc1394_log_debug("Frame captured successfully");
333
    } else if (err != DC1394_SUCCESS) {
334
        // Always log errors
335
        dc1394_log_error("Frame capture failed: " + err);
336
    }
337
}
338
```
339

340
### Exception Handling Integration
341

342
Combine logging with proper exception handling:
343

344
```java
345
public void setupCamera() throws CameraException {
346
    try {
347
        int err = dc1394_video_set_mode(camera, video_mode);
348
        if (err != DC1394_SUCCESS) {
349
            String error_msg = "Failed to set video mode: " + 
350
                             dc1394_error_get_string(err).getString();
351
            dc1394_log_error(error_msg);
352
            throw new CameraException(error_msg, err);
353
        }
354
        dc1394_log_debug("Video mode set successfully");
355
    } catch (Exception e) {
356
        dc1394_log_error("Unexpected exception in camera setup: " + e.getMessage());
357
        throw new CameraException("Camera setup failed", e);
358
    }
359
}
360
```
361

362
This logging system provides comprehensive error reporting and debugging capabilities for libdc1394 applications.