itunes_server/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a C++ Windows DLL project that provides iTunes gift card redemption functionality through the iTunes Store API. The project creates a dynamic library (iTunesAPIs.dll) that wraps iTunes client functionality for automated gift card redemption.

Build System

Build Commands

This project uses Visual Studio 2022 (v143 toolset) with MSBuild:

# Build the entire solution (both DLL and debugger)
msbuild "iTunes礼品卡兑换_DLL封装.sln" /p:Configuration=Release /p:Platform=Win32

# Build only the DLL
msbuild "iTunesAPIs\iTunesAPIs.vcxproj" /p:Configuration=Release /p:Platform=Win32

# Build with debug information
msbuild "iTunesAPIs\iTunesAPIs.vcxproj" /p:Configuration=Debug /p:Platform=Win32

Build Configurations

• Release|Win32: Primary configuration for production builds
• Debug|Win32: Development builds with debug symbols
• Output Directory: bin\$(Configuration)\$(Platform)\
• Target Name: iTunesAPIs.dll

Dependencies

The project links against several third-party libraries located in third_party\:

• libcurl: HTTP client functionality
• OpenSSL: Cryptographic operations
• Google Logging (glog): Logging framework
• 7zip: Archive extraction for iTunes DLL resources
• Custom cookie parsing library

Architecture

Core Components

1. iTunesAPIs Namespace: DLL entry points for initialization

   • init_dll(): Extracts and sets up iTunes DLL dependencies
   • init_environment(): Configures proxy settings

2. iTunesFunctions Namespace: Main API functions

   • Authentication: iTunes_login(), iTunes_logout(), iTunes_login_status()
   • Gift Card Operations: iTunes_redeem()
   • Account Management: iTunes_summary()
   • Utilities: iTunes_free(), iTunes_get_heartbeat_list()

3. iTunesCore Module (src/iTunesCore/): Low-level iTunes integration

   • itunes_module.{cc,h}: Manages iTunes DLL paths and environment
   • itunes_client_interface.cc: iTunes client communication
   • itunes_https.cc: HTTPS communication layer
   • itunes_cookie_interface.cc: Cookie management
   • Windows integration: windows_hardware.cc, windows_version.cc

4. Authentication Module (src/authenticate/):

   • License/authentication system using access keys
   • Supports Agent and User authentication types

5. Utilities (src/utils/):

   • HTTP request wrapper with cookie/header management
   • String manipulation and encoding utilities
   • JSON parsing with jsoncpp
   • Hardware fingerprinting

Key Design Patterns

• Singleton Pattern: Authentication system uses Instance() method
• Resource Management: iTunes DLLs are embedded as resources and extracted at runtime
• Environment Setup: Dynamic PATH modification to load iTunes dependencies
• Thread Safety: Keep-alive thread for maintaining session state

Important Implementation Details

DLL Resource Management

The project embeds iTunes DLL files as resources and extracts them on first run:

• Resources defined in src\Resource.rc
• Extraction handled in src\writeResourceFile.cpp
• Uses 7zip library for decompression

Memory Management

• All string output from DLL functions must be freed using iTunes_free()
• Uses C-style allocation for cross-language compatibility

Proxy Support

The API supports HTTP/SOCKS proxies through:

• init_environment() function for global proxy setup
• Per-function proxy parameters for individual requests

Error Handling

Functions return integer codes and output JSON-formatted error messages via char** parameters.

Development Notes

Testing

The iTunes接口调试器 (iTunes Interface Debugger) project provides a test harness for the DLL functionality.

Platform Requirements

• Windows 10 or later (Windows Target Platform Version 10.0)
• Visual Studio 2022 (Toolset v143)
• C++17 standard compliance
• Win32 architecture (primary target)

Security Considerations

This codebase handles sensitive authentication credentials and gift card codes. The authentication module appears to implement a licensing system to control access to the DLL functionality.