001/*******************************************************************************
002 * Copyright (c) 2024, 2026, Olivier Ayache.  All rights reserved.
003 *
004 * This file is part of AVPKit.
005 *
006 * AVPKit is free software: you can redistribute it and/or modify
007 * it under the terms of the GNU Lesser General Public License as published by
008 * the Free Software Foundation, either version 3 of the License, or
009 * (at your option) any later version.
010 *
011 * AVPKit is distributed in the hope that it will be useful,
012 * but WITHOUT ANY WARRANTY; without even the implied warranty of
013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014 * GNU Lesser General Public License for more details.
015 *
016 * You should have received a copy of the GNU Lesser General Public License
017 * along with AVPKit.  If not, see <http://www.gnu.org/licenses/>.
018 *******************************************************************************/
019
020package com.avpkit.core;
021
022/**
023 * Methods that implement this interface can be configuring
024 * using setProperty and getProperty methods, and expose
025 * {@link IProperty} meta data about their properties.
026 * <p>
027 * You can use {@link Configuration#configure(java.util.Properties, IConfigurable)}
028 * to easily configure these objects from Java properties or
029 * from a FFmpeg preset file.
030 * </p>
031 * @see Configuration#configure(java.util.Properties, IConfigurable)
032 * 
033 * @author aclarke
034 *
035 */
036public interface IConfigurable
037{
038  /**
039   * Gets a collection of all properties settable on this object.
040   * You can then query current settings with {@link #getPropertyAsString(String)}
041   * and set properties with {@link #setProperty(String, String)}.
042   * @return a collection of all properties for this object.
043   */
044  public java.util.Collection<String> getPropertyNames();
045  
046  /**
047   * Returns the total number of settable properties on this object  
048   * @return      total number of options (not including constant definitions) 
049   *                
050   */
051  public int getNumProperties();
052
053  /**
054   * Returns the name of the numbered property.  
055   * @param       propertyNo The property number in the options list.  
056   * @return      an IProperty value for this properties meta-data  
057   */
058  public IProperty getPropertyMetaData(int propertyNo);
059
060  /**
061   * Returns the name of the numbered property.  
062   * @param       name The property name.  
063   * @return      an IProperty value for this properties meta-data  
064   */
065  public IProperty getPropertyMetaData(String name);
066
067  /**
068   * Sets a property on this Object.  
069   * All AVOptions supported by the underlying AVClass are supported. 
070   *  
071   * @param       name The property name. For example "b" for bit-rate.  
072   * @param       value The value of the property.  
073   * @return      >= 0 if the property was successfully set; <0 on error  
074   */
075  public int setProperty(String name, String value);
076
077  /**
078   * Looks up the property 'name' and sets the  
079   * value of the property to 'value'.  
080   * @param       name name of option  
081   * @param       value Value of option  
082   * @return      >= 0 on success; <0 on error.  
083   */
084  public int setProperty(String name, double value);
085
086  /**
087   * Looks up the property 'name' and sets the  
088   * value of the property to 'value'.  
089   * @param       name name of option  
090   * @param       value Value of option  
091   * @return      >= 0 on success; <0 on error.  
092   */
093  public int setProperty(String name, long value);
094
095  /**
096   * Looks up the property 'name' and sets the  
097   * value of the property to 'value'.  
098   * @param       name name of option  
099   * @param       value Value of option  
100   * @return      >= 0 on success; <0 on error.  
101   */
102  public int setProperty(String name, boolean value);
103
104  /**
105   * Looks up the property 'name' and sets the  
106   * value of the property to 'value'.  
107   * @param       name name of option  
108   * @param       value Value of option  
109   * @return      >= 0 on success; <0 on error.  
110   */
111  public int setProperty(String name, IRational value);
112
113  /**
114   * Gets a property on this Object.  
115   * Note for C++ callers; you must free the returned array with  
116   * delete[] in order to avoid a memory leak. Other language  
117   * folks need not worry.  
118   * @param       name property name  
119   * @return      an string copy of the option value, or null if the option 
120   *               doesn't exist.  
121   */
122  public String getPropertyAsString(String name);
123
124  /**
125   * Gets the value of this property, and returns as a double;  
126   * @param       name name of option  
127   * @return      double value of property, or 0 on error.  
128   */
129  public double getPropertyAsDouble(String name);
130
131  /**
132   * Gets the value of this property, and returns as an long;  
133   * @param       name name of option  
134   * @return      long value of property, or 0 on error.  
135   */
136  public long getPropertyAsLong(String name);
137
138  /**
139   * Gets the value of this property, and returns as an IRational;  
140   * @param       name name of option  
141   * @return      long value of property, or 0 on error.  
142   */
143  public IRational getPropertyAsRational(String name);
144
145  /**
146   * Gets the value of this property, and returns as a boolean  
147   * @param       name name of option  
148   * @return      boolean value of property, or false on error.  
149   */
150  public boolean getPropertyAsBoolean(String name);
151  
152  /**
153   * Sets all properties in valuesToSet on this {@link IConfigurable} object.
154   *
155   * @param valuesToSet The set of key-value pairs to try to set
156   * @param valuesNotFound If non null will contain all key-values pairs in valuesToSet
157   *                       that were not found in context.
158   *
159   * @return 0 on success; <0 on failure
160   * @since 5.0
161   */  
162  public int setProperty(IMetaData valuesToSet, IMetaData valuesNotFound);
163  
164
165}